Pulumi Blog: Typescript

Incident Response as Code: Managing PagerDuty with Pulumi

Engin Diri — Mon, 20 Jul 2026 00:00:00 +0000

You usually find out in the postmortem: the alarm fired, but it paged a schedule nobody was on anymore. Or the service had been running in production for three months before anyone created the matching PagerDuty service, so the first person to notice the outage was a customer. The infrastructure was code, reviewed and versioned. The incident response setup was forty clicks in a web UI, done once, by someone who has since changed teams.

PagerDuty’s own engineering team has been making the case for managing PagerDuty as code for years, and the OneUptime folks recently published a hands-on guide to the PagerDuty Terraform provider that walks the whole resource catalog. I liked both posts, and you probably know where this is going: I want the same thing in TypeScript, with the on-call setup and the infrastructure it protects living in the same Pulumi program. Teams, schedules, escalation policies, services, and the CloudWatch alarm that pages you: one pulumi up.

What you are building

The demo models a small platform team that owns a checkout service on AWS. On the PagerDuty side: a team with three members, a weekly on-call rotation, an escalation policy with two levels, and a service with a CloudWatch integration. On the AWS side: a dead-letter queue, an alarm that fires when a message lands in it, and an SNS topic that forwards the alarm to PagerDuty. The interesting part is where the two meet: the integration key PagerDuty mints flows straight into the SNS subscription without ever touching a clipboard.

flowchart LR
DLQ["SQS dead-letter queue"] --> Alarm["CloudWatch alarm"]
Alarm --> SNS["SNS topic"]
SNS -->|"HTTPS subscription<br/>with integration key"| Int["CloudWatch integration"]
Int --> Svc["PagerDuty service<br/>Checkout API"]
Svc --> EP["Escalation policy"]
EP -->|"level 1"| Sched["Weekly rotation<br/>Lena, Jonas, Mia"]
EP -->|"level 2, after 15 min"| Lead["Team lead"]

Everything on both sides of that diagram is one TypeScript program. If you would rather write Python, JavaScript, Go, .NET, Java, or YAML, the Pulumi PagerDuty provider supports all of them. It is bridged from PagerDuty’s official Terraform provider (which started life as a community project by Alexander Hellbom before PagerDuty adopted it), so the resource coverage is identical.

Prerequisites

Before getting started, ensure you have:

Pulumi CLI installed and configured
A Pulumi Cloud account
A PagerDuty account with admin access; a free trial works fine
An AWS account for the alarm wiring in the second half
Node.js 18+ for the TypeScript program

The provider and the token

Create a new project and add the PagerDuty provider:

pulumi new aws-typescript --name pagerduty-oncall
npm install @pulumi/pagerduty

The provider authenticates with a REST API key. In PagerDuty, navigate to Integrations > API Access Keys and create a new key. This is the account-level REST API key, not a user token: user tokens are scoped to what one person can see, and you want the automation to manage the whole account.

I store the key in Pulumi ESC so it never lands in a .env file, shell history, or agent context:

pulumi env init <your-org>/pagerduty-demo/dev

Add the token to the environment definition:

values:
 pagerduty:
 token:
 fn::secret: <your-rest-api-key>
 pulumiConfig:
 pagerduty:token: ${pagerduty.token}

Then reference the environment from your stack in Pulumi.dev.yaml:

environment:
 - <your-org>/pagerduty-demo/dev

In a hurry? pulumi config set pagerduty:token --secret does the same job for a single stack, and the provider also reads the PAGERDUTY_TOKEN environment variable. If your account lives on the EU service region, additionally set pagerduty:serviceRegion to eu.

Teams, users, and memberships

Everything in PagerDuty hangs off teams and users, so that is where the program starts:

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

const platformTeam = new pagerduty.Team("platform-team", {
 name: "Platform Engineering",
 description: "Owns the checkout path and the shared platform",
});

const lena = new pagerduty.User("lena", {
 name: "Lena Fischer",
 email: "lena@example.com",
});

const jonas = new pagerduty.User("jonas", {
 name: "Jonas Weber",
 email: "jonas@example.com",
});

const mia = new pagerduty.User("mia", {
 name: "Mia Schneider",
 email: "mia@example.com",
});

new pagerduty.TeamMembership("lena-platform", {
 userId: lena.id,
 teamId: platformTeam.id,
 role: "manager",
});

new pagerduty.TeamMembership("jonas-platform", {
 userId: jonas.id,
 teamId: platformTeam.id,
 role: "responder",
});

new pagerduty.TeamMembership("mia-platform", {
 userId: mia.id,
 teamId: platformTeam.id,
 role: "responder",
});

Three users, one team, three memberships. Reorgs stop being an afternoon of UI archaeology and become a pull request where the diff shows exactly who moved where.

If your users already come from SSO or SCIM provisioning (they usually do), don’t create them in the program. Look them up instead with the getUser data source: pagerduty.getUserOutput({ email: "lena@yourcompany.com" }). And if your account restricts sign-ups to your company’s email domain, the API enforces that too, so swap the example.com addresses for ones on your own domain when trying this out.

A schedule people can live with

The on-call schedule is where incident response meets real life, so it deserves more care than a demo usually gives it. If you have seen PagerDuty schedules in Terraform before, you probably remember the Schedule resource and its layers. That resource is deprecated in the current provider because it speaks the legacy v1 schedules API; its successor Schedulev2 uses PagerDuty’s new model built on rotations, events, and RFC 5545 recurrence rules:

const primary = new pagerduty.Schedulev2("primary", {
 name: "Platform Primary On-Call",
 description: "Weekly hand-off rotation for the platform team",
 timeZone: "Europe/Berlin",
 teams: [platformTeam.id],
 rotations: [{
 events: [{
 name: "Weekly rotation",
 startTime: "2026-08-03T09:00:00+02:00",
 endTime: "2026-08-10T09:00:00+02:00",
 effectiveSince: "2026-08-03T07:00:00Z",
 recurrences: ["RRULE:FREQ=WEEKLY;BYDAY=MO"],
 assignmentStrategies: [{
 type: "rotating_member_assignment_strategy",
 shiftsPerMember: 1,
 members: [
 { type: "user_member", userId: lena.id },
 { type: "user_member", userId: jonas.id },
 { type: "user_member", userId: mia.id },
 ],
 }],
 }],
 }],
});

Read it from the inside out. The event is one shift: it starts Monday at 09:00 Berlin time and ends the following Monday at 09:00, and the RRULE makes it recur weekly. The assignment strategy hands each occurrence to the next member in the list, so Lena, Jonas, and Mia each take a full week, round robin. effectiveSince tells PagerDuty when this configuration starts producing shifts. Business-hours-only coverage falls out of the same model: shorten the shift window and change the recurrence to RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR.

The escalation policy

The escalation policy reads top to bottom, the same way the incident will play out:

const escalation = new pagerduty.EscalationPolicy("platform-escalation", {
 name: "Platform Escalation Policy",
 numLoops: 2,
 teams: platformTeam.id,
 rules: [
 {
 escalationDelayInMinutes: 15,
 targets: [{
 type: "schedule_reference",
 id: primary.id,
 }],
 },
 {
 escalationDelayInMinutes: 10,
 targets: [{
 type: "user_reference",
 id: lena.id,
 }],
 },
 ],
});

Page whoever the primary schedule says is on call. If nobody acknowledges within 15 minutes, page Lena directly. If the whole chain runs dry, numLoops: 2 starts it over twice more before PagerDuty gives up. When someone asks what actually happens when this fires at 3 AM, the answer is a dozen lines of reviewed code, not a screenshot of a UI that may or may not be current.

The service

A PagerDuty service is the unit incidents attach to, and it is where the escalation policy gets wired in:

const checkoutService = new pagerduty.Service("checkout", {
 name: "Checkout API",
 escalationPolicy: escalation.id,
 autoResolveTimeout: "14400",
 acknowledgementTimeout: "600",
});

Think of a service as the thing that can break, like the checkout API or the payments queue behind it. Every incident in PagerDuty opens against exactly one service, and the service decides what happens next. The escalation policy answers who gets paged. acknowledgementTimeout re-triggers an incident that was acknowledged and then went quiet for ten minutes, so a sleepy “ack” cannot make a problem disappear. And autoResolveTimeout closes an incident that has sat open for four hours, which keeps the dashboard honest when everyone forgot to press resolve. Map services one-to-one to the things your team actually owns, and the service directory turns into an honest inventory of your system, each entry with an owner attached.

So far this is a nicer syntax for what the Terraform guides already do. Here is where it starts earning its keep. Remember the service from the top of this post that ran for three months without a pager? The place that failure usually hides is a dead-letter queue, where bad news piles up quietly. This is what it looks like when the queue, the alarm, and the pager live in one program:

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

const cloudwatch = pagerduty.getVendorOutput({ name: "Amazon CloudWatch" });

const checkoutIntegration = new pagerduty.ServiceIntegration("checkout-cloudwatch", {
 name: "Amazon CloudWatch",
 service: checkoutService.id,
 vendor: cloudwatch.id,
});

const alarmTopic = new aws.sns.Topic("checkout-alarms");

new aws.sns.TopicSubscription("checkout-alarms-to-pagerduty", {
 topic: alarmTopic.arn,
 protocol: "https",
 endpoint: pulumi.interpolate`https://events.pagerduty.com/integration/${checkoutIntegration.integrationKey}/enqueue`,
 endpointAutoConfirms: true,
});

const dlq = new aws.sqs.Queue("checkout-dlq");

new aws.cloudwatch.MetricAlarm("checkout-dlq-alarm", {
 alarmDescription: "Messages are landing in the checkout dead-letter queue",
 namespace: "AWS/SQS",
 metricName: "ApproximateNumberOfMessagesVisible",
 dimensions: {
 QueueName: dlq.name,
 },
 statistic: "Maximum",
 period: 60,
 evaluationPeriods: 1,
 threshold: 1,
 comparisonOperator: "GreaterThanOrEqualToThreshold",
 alarmActions: [alarmTopic.arn],
 okActions: [alarmTopic.arn],
});

Follow the integration key. PagerDuty mints it when the ServiceIntegration is created, and a few lines later it is interpolated into the SNS subscription endpoint. In the two-tool world, this is the step where you open the PagerDuty UI, copy the integration URL, and paste it into a variables file or a wiki page, which is exactly the step that gets skipped at 5 PM on a Friday. Here it cannot be skipped, because it is a dependency: Pulumi will not create the subscription before the integration exists.

endpointAutoConfirms: true matters because PagerDuty answers the SNS subscription handshake on its own; without it, the subscription sits in “pending confirmation” forever. And since the alarm sends its OK state to the same topic, PagerDuty resolves the incident automatically once the queue drains.

Tearing down the service? The alarm, the topic, the subscription, and the PagerDuty service all go in the same pulumi destroy, which spares you the orphaned PagerDuty service that keeps paging people about infrastructure that no longer exists. I have seen that one too.

Azure and Google Cloud, same trick

Nothing about this is AWS-specific. It is always the same two steps: PagerDuty mints a key, the monitoring side consumes it. On Google Cloud, Cloud Monitoring has a native PagerDuty channel type, and its serviceKey is the integration key of an Events API v2 integration:

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

const gcpIntegration = new pagerduty.ServiceIntegration("checkout-gcp", {
 name: "Google Cloud Monitoring",
 service: checkoutService.id,
 type: "events_api_v2_inbound_integration",
});

new gcp.monitoring.NotificationChannel("checkout-pagerduty", {
 displayName: "PagerDuty: Checkout API",
 type: "pagerduty",
 sensitiveLabels: {
 serviceKey: gcpIntegration.integrationKey,
 },
});

On Azure, an Azure Monitor action group with a webhook receiver does the same job, pointed at the familiar enqueue URL (with resourceGroup being an azure.resources.ResourceGroup from earlier in your program):

import * as azure from "@pulumi/azure-native";

const azureVendor = pagerduty.getVendorOutput({ name: "Microsoft Azure" });

const azureIntegration = new pagerduty.ServiceIntegration("checkout-azure", {
 name: "Microsoft Azure",
 service: checkoutService.id,
 vendor: azureVendor.id,
});

new azure.monitor.ActionGroup("checkout-pagerduty", {
 resourceGroupName: resourceGroup.name,
 location: "global",
 groupShortName: "checkout",
 enabled: true,
 webhookReceivers: [{
 name: "pagerduty",
 serviceUri: pulumi.interpolate`https://events.pagerduty.com/integration/${azureIntegration.integrationKey}/enqueue`,
 useCommonAlertSchema: true,
 }],
});

The location: "global" is not a placeholder. Action groups are a global service, and Azure rejects regular regions like westeurope for them; setting it explicitly makes that intent obvious in the code.

Same program, same key handoff, different cloud. If your platform spans all three, the PagerDuty side does not care.

Breaking a Fargate payment service on purpose

Everything so far wires configuration together, but I did not want to publish wiring I had never watched fire. So I put it to the test: a companion project that deploys a small payment service on AWS Fargate together with its entire failure chain, and then breaks it on purpose.

The worker is deliberately boring: the plain AWS CLI container image running a shell loop. It receives payment messages from an SQS queue, processes anything that has an amount, and refuses everything else. A refused message goes back to the queue, and after three failed receives SQS moves it to the dead-letter queue. From there, the chain from earlier in this post takes over: DLQ alarm, SNS topic, CloudWatch integration, escalation policy, phone.

A valid payment flows through in seconds:

./scripts/send-payment.sh
# worker log: processed payment: {"orderId":"4711","amount":"49.99","currency":"EUR"}

A payment without an amount poisons the queue:

./scripts/inject-failure.sh

Here is the timeline from my test run, as the test script observed it through the AWS and PagerDuty APIs:

Elapsed	What happened
0:00	Poison payment injected
3:45	Third receive failed, message redriven to the DLQ, alarm in `ALARM`
3:49	PagerDuty incident triggered on Payment Service
3:50	Recovery: dead-letter queue purged
6:48	Alarm back to `OK`
6:49	Incident resolved

Under four minutes from a bad message to a page, and I never touched the PagerDuty UI in either direction; the incident opened and closed itself off the alarm’s state transitions. The incident timeline spells it out: automatically triggered and assigned, then resolved through the integration API.

The full program, the worker loop, and the inject and recover scripts are in the companion repo:

github.com/dirien/pulumi-pagerduty-fargate-demo

Growing without the drift: a reusable component

Whether any of this stays consistent as your organization grows comes down to defaults. If creating a properly paged service takes a checklist, people will skip items. If it takes a component, they won’t, because the component is less work than the checklist. So wrap the service, the integration, and the alarm topic into one:

export class OnCallService extends pulumi.ComponentResource {
 public readonly service: pagerduty.Service;
 public readonly alarmTopic: aws.sns.Topic;

 constructor(name: string, args: {
 displayName: string;
 escalationPolicy: pulumi.Input<string>;
 }, opts?: pulumi.ComponentResourceOptions) {
 super("acme:oncall:OnCallService", name, {}, opts);

 this.service = new pagerduty.Service(name, {
 name: args.displayName,
 escalationPolicy: args.escalationPolicy,
 autoResolveTimeout: "14400",
 acknowledgementTimeout: "600",
 }, { parent: this });

 const cloudwatch = pagerduty.getVendorOutput({ name: "Amazon CloudWatch" });

 const integration = new pagerduty.ServiceIntegration(name, {
 name: "Amazon CloudWatch",
 service: this.service.id,
 vendor: cloudwatch.id,
 }, { parent: this });

 this.alarmTopic = new aws.sns.Topic(name, {}, { parent: this });

 new aws.sns.TopicSubscription(name, {
 topic: this.alarmTopic.arn,
 protocol: "https",
 endpoint: pulumi.interpolate`https://events.pagerduty.com/integration/${integration.integrationKey}/enqueue`,
 endpointAutoConfirms: true,
 }, { parent: this });

 this.registerOutputs({});
 }
}

And now every new service ships with a pager attached. The checkout instance here replaces the hand-rolled service, integration, and topic from earlier:

const checkout = new OnCallService("checkout", {
 displayName: "Checkout API",
 escalationPolicy: escalation.id,
});

const payments = new OnCallService("payments", {
 displayName: "Payments API",
 escalationPolicy: escalation.id,
});

App teams get one contract: point your alarms at alarmTopic. The escalation policy, the timeouts, the integration, the SNS wiring, all of it becomes the paved road instead of a checklist item. This is the same components-and-templates story I keep telling for compute and networking; incident response just turns out to be another thing a platform team can pave.

Importing what you already clicked together

Nobody starts from an empty PagerDuty account. The realistic adoption path is pulumi import, resource by resource:

pulumi import pagerduty:index/team:Team platform-team PXXXXXX
pulumi import pagerduty:index/service:Service checkout PYYYYYY

The IDs are in the URL when you open a team or service in the PagerDuty web UI, and pulumi import writes the matching code for you, so bringing an existing setup under management is mostly a copy-paste loop. The import guide covers the mechanics.

One habit matters after that, and PagerDuty’s engineering post makes the same point about Terraform: once a resource is managed as code, stop editing it in the UI. Changes made in the web console are drift, and you will want to run pulumi refresh (or let drift detection do it on a schedule) to catch them before the 3 AM page tests your assumptions for you.

Conclusion

The pitch for managing PagerDuty as code has less to do with YAML versus HCL versus TypeScript than with the gap between two systems that each hold half the truth. Your infrastructure code knows a queue exists; PagerDuty knows who gets paged when it backs up. Keep them in separate tools and that gap is maintained by hand, which means it is maintained until the person who cared about it leaves.

Putting both sides in one Pulumi program closes the gap structurally. The integration key becomes a dependency edge instead of a wiki entry, and forgetting the escalation policy is not even possible, because escalationPolicy is a required property and the program will not compile without it. That is the version of “nothing gets forgotten” I am willing to rely on.

To go further:

The PagerDuty provider in the Pulumi Registry covers the full resource catalog: event orchestrations, maintenance windows, response plays, and more.
Pulumi ESC keeps the API token out of your shell history.
Coming from the Terraform provider? Your resource knowledge maps one-to-one, and the migration guide covers the rest.

If you build something with this, or if your on-call setup has a horror story that code would have prevented, come tell me in the Pulumi Community Slack.

Fully Automated AI Inference on AWS, Azure, and Google Cloud with Pulumi

Engin Diri — Tue, 30 Jun 2026 00:00:00 +0000

Putting Ollama on a cloud GPU is something I keep coming back to. A while ago I wrote up running open-source LLMs on an AWS EC2 box with Ollama and Pulumi, and the shape never really changes: a GPU instance, a model server, and a firewall rule in front. Infrastructure as code earned its place by making that kind of setup predictable and repeatable, and AI infrastructure is no exception. A GPU box serving a model is still a VM, a disk, and a firewall rule, and it should be declared like one.

Thorsten Hans made exactly that case in his Akamai post, Fully Automated AI Infrastructures with Terraform and Akamai Cloud, which stands up a single GPU instance on Linode, installs the drivers, runs Ollama, and pulls a model, with no manual steps after terraform apply.

I liked the shape of it, so this post ports the same idea to Pulumi and runs it across AWS, Azure, and Google Cloud instead of one. The result is one program shape per cloud: a single pulumi up brings up a GPU box that installs its own driver, runs Ollama, and pulls a model with no manual steps, and a single pulumi destroy takes it back down. Along the way it drops the two imperative bits the Terraform version leans on: a static access token sitting in an environment variable, and a null_resource running a shell loop to wait for the model. The first becomes an OIDC login from a Pulumi ESC environment, so no long-lived key lives anywhere. The second turns out not to be a resource at all.

What you are building

Strip away the per-cloud naming and every version of this is the same three things: a GPU virtual machine, a firewall in front of it, and a cloud-init script that turns a bare Ubuntu box into a running inference server. The model serving runs on Ollama, which exposes an HTTP API on port 11434 and keeps the model resident in GPU memory between requests.

flowchart LR
Dev([Your machine / curl]) -->|"HTTP :11434"| FW["Firewall / security group<br/>(allow 11434, optional 22)"]
FW --> VM["GPU VM (Ubuntu 24.04)<br/>NVIDIA driver + Ollama"]
VM -->|"resident in GPU memory"| Model["qwen2.5:14b"]
ESC["Pulumi ESC<br/>pulumi-idp/auth"] -.->|"OIDC login (short-lived creds)"| Pulumi["pulumi up"]
Pulumi -.->|"AWS / Azure / GCP"| VM

Component	Port	Description
GPU VM	-	Ubuntu 24.04 with an NVIDIA T4-class GPU. Installs the driver and Ollama from cloud-init, then pulls the model.
Ollama	11434	Serves the model over an HTTP API and keeps it in GPU memory between calls.
Firewall / security group	-	Allows inbound `11434` (and `22` when you ask for it). Open to the world for a demo; lock the CIDR down for anything real.
`pulumi-idp/auth` (ESC)	-	One environment that brokers an OIDC login into AWS, Azure, and GCP. No static keys in code or CI.

One detail here is worth pausing on, and it explains why the Pulumi version comes out shorter than the Terraform one. The Akamai project ends with a null_resource that runs a curl loop in local-exec to block terraform apply until the model finishes downloading. That is not infrastructure but a runtime check wearing a resource costume. Pulumi has a Command provider that would let you reproduce it line for line, and this post deliberately does not. The program provisions the box, the box pulls the model on its own, and the program prints the endpoint. Whether the model has finished downloading yet is a question you answer with a curl, not a question your IaC tool should be holding a deployment open to ask.

Prerequisites

Before getting started, ensure you have:

Pulumi CLI installed and configured
A Pulumi Cloud account (ESC and OIDC live here)
An account on at least one of AWS, Azure, or Google Cloud, with an OIDC trust set up for Pulumi (covered below)
Enough GPU quota in your target region for one T4-class instance; a fresh account often starts at zero, which is the most common reason a first deploy fails, so check it before you run pulumi up
Node.js 18+ for the TypeScript program
curl to talk to the inference endpoint once it comes up

This post serves the qwen2.5:14b model, the same one the Akamai article uses, because the 4-bit quant fits comfortably on a single 16 GB T4. The model is one config value (model), so swap in anything Ollama supports; match the GPU to the model’s memory footprint, because a model that overflows VRAM still runs but spills onto the CPU and crawls.

Credentials without the copy-paste

The Terraform version authenticates the only way a single-cloud demo can: you mint a personal access token, export it as LINODE_TOKEN, and the provider reads it from the environment. It works, but that token is long-lived, it sits in your shell history and your CI secrets, and you mint one per cloud. Across three clouds that is three static keys to rotate and worry about.

Pulumi ESC (Environments, Secrets, and Configuration) replaces it all with an OIDC login. The idea: instead of storing a cloud key, you store a trust relationship. At deploy time, ESC presents a short-lived OIDC token to AWS, Azure, or Google Cloud, and each one hands back temporary credentials scoped to a role you control. Nothing long-lived is ever written down.

I keep that wiring in one environment, pulumi-idp/auth, and every stack imports it. Here is the whole thing:

# pulumi-idp/auth: one ESC environment that brokers an OIDC login into all three
# clouds. Every stack imports it. No static cloud key lives here or anywhere else.
values:
 aws:
 login:
 fn::open::aws-login:
 oidc:
 roleArn: arn:aws:iam::123456789012:role/pulumi-esc
 sessionName: pulumi-esc
 azure:
 login:
 fn::open::azure-login:
 clientId: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
 tenantId: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
 subscriptionId: /subscriptions/00000000-0000-0000-0000-000000000000
 oidc: true
 gcp:
 login:
 fn::open::gcp-login:
 project: 123456789012 # numeric project number, not the project ID
 oidc:
 workloadPoolId: pulumi-esc
 providerId: pulumi-esc
 serviceAccount: pulumi-esc@my-project.iam.gserviceaccount.com
 environmentVariables:
 # AWS: read by the Pulumi AWS provider, the AWS SDKs, and the aws CLI
 AWS_ACCESS_KEY_ID: ${aws.login.accessKeyId}
 AWS_SECRET_ACCESS_KEY: ${aws.login.secretAccessKey}
 AWS_SESSION_TOKEN: ${aws.login.sessionToken}
 # Azure: read by the azure-native provider
 ARM_USE_OIDC: "true"
 ARM_CLIENT_ID: ${azure.login.clientId}
 ARM_TENANT_ID: ${azure.login.tenantId}
 ARM_SUBSCRIPTION_ID: ${azure.login.subscriptionId}
 ARM_OIDC_TOKEN: ${azure.login.oidc.token}
 # Google Cloud: read by the Pulumi Google Cloud provider
 GOOGLE_CLOUD_PROJECT: ${gcp.login.project}
 GOOGLE_OAUTH_ACCESS_TOKEN: ${gcp.login.accessToken}

You only need the blocks for the clouds you actually deploy to. Opening this environment makes ESC perform a live OIDC login for each cloud listed, so trim it to the one you use, or keep all three if, like me, you bounce between them.

Each cloud needs a one-time trust setup so this login is allowed at all: an IAM OIDC identity provider and role on AWS, a federated credential on an Azure app registration, and a Workload Identity Pool on Google Cloud. You do that once; after that, pulumi-idp/auth is the only thing any stack references for credentials.

A stack opts into it with one block in its stack config. The AWS stack’s Pulumi.aws.yaml:

# Pulumi.aws.yaml
environment:
 - pulumi-idp/auth

That is the entire credential story. No keys in the program, no keys in CI, nothing to rotate. The program below never mentions a secret; it only creates resources, and the ambient credentials from pulumi-idp/auth carry the request.

One cloud-init, three clouds

The part that turns a bare Ubuntu box into an inference server is identical on every cloud, so it lives in one file, cloud-init.yaml, that all three programs read. It follows the Akamai cloud-config closely, with a couple of robustness tweaks for a multi-cloud run, and it runs in a deliberate order because the GPU driver needs a reboot before Ollama can see the card:

Update packages and install the kernel headers and ubuntu-drivers.
Install the NVIDIA driver, then reboot so the kernel loads it.
On the next boot, a one-shot systemd service installs Ollama, binds it to 0.0.0.0:11434, and pulls the model.
The service disables itself, so it never runs again.

#cloud-config
# Zero-touch Ollama GPU box. Cloud-agnostic: no provider metadata, no static creds.
# The Pulumi program substitutes the model name on the `ollama pull` line below
# before this is passed as user-data (AWS/GCP) or custom-data (Azure).

write_files:
 # Make Ollama listen on every interface and never unload the model from VRAM.
 - path: /etc/systemd/system/ollama.service.d/override.conf
 content: |
 [Service]
 Environment="OLLAMA_HOST=0.0.0.0:11434"
 Environment="OLLAMA_KEEP_ALIVE=-1"

 # Runs once on the post-reboot boot, after the GPU driver is loaded.
 - path: /usr/local/bin/ollama-setup.sh
 permissions: '0755'
 content: |
 #!/usr/bin/env bash
 set -euxo pipefail

 # Install Ollama; the installer creates and starts the ollama systemd unit.
 curl -fsSL https://ollama.com/install.sh | sh

 # Pick up the OLLAMA_HOST / OLLAMA_KEEP_ALIVE override written above.
 systemctl daemon-reload
 systemctl enable ollama.service
 systemctl restart ollama.service

 # Wait for the daemon to bind its socket before pulling. This is the box
 # waiting on its OWN local daemon, not an external readiness gate.
 until curl -fsS http://127.0.0.1:11434/api/tags >/dev/null 2>&1; do
 sleep 2
 done

 # Pre-pull the model so the endpoint answers on the very first request.
 ollama pull __MODEL__

 # One-shot: never run again on future boots.
 systemctl disable ollama-setup.service

 - path: /etc/systemd/system/ollama-setup.service
 content: |
 [Unit]
 Description=One-time Ollama install and model pull
 After=network-online.target
 Wants=network-online.target

 [Service]
 Type=oneshot
 ExecStart=/usr/local/bin/ollama-setup.sh
 RemainAfterExit=true
 # The model pull runs for several minutes; without this, systemd's default
 # 90s start timeout kills the service mid-download and the model never lands.
 TimeoutStartSec=0

 [Install]
 WantedBy=multi-user.target

runcmd:
 - apt-get update
 - DEBIAN_FRONTEND=noninteractive apt-get -y upgrade
 # linux-headers-generic also covers the kernel the upgrade above may have pulled
 # in, so DKMS builds the NVIDIA module for the kernel that boots next.
 - DEBIAN_FRONTEND=noninteractive apt-get install -y "linux-headers-$(uname -r)" linux-headers-generic ubuntu-drivers-common
 # --gpgpu selects the headless server driver branch, the right one for a compute
 # GPU like the T4; bare `ubuntu-drivers install` would pull the desktop stack.
 - ubuntu-drivers install --gpgpu
 - systemctl enable ollama-setup.service

power_state:
 mode: reboot
 message: Rebooting to load the NVIDIA driver before Ollama setup
 condition: true

The model name is the literal token __MODEL__. The Pulumi program reads this file at deploy time and substitutes your model config value before handing it to the instance. Two environment settings are doing quiet but important work: OLLAMA_HOST=0.0.0.0:11434 makes Ollama listen on every interface instead of localhost alone, and OLLAMA_KEEP_ALIVE=-1 keeps the model pinned in GPU memory so only the first request pays the load cost.

The programs

Every program has the same five beats: read the config, template the cloud-init.yaml, open the inbound ports, launch the GPU instance with that cloud-init as its user data, and export the endpoint. What differs is only the dialect each cloud speaks for “GPU instance” and “firewall rule.”

The shared contract keeps the three listings legible side by side: the same model and allowSsh config keys, the same cloud-init.yaml, and the same four exports (publicIp, ollamaEndpoint, generateEndpoint, tagsEndpoint). Pick your cloud:

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

const cfg = new pulumi.Config();
const model = cfg.get("model") ?? "qwen2.5:14b";
const allowSsh = cfg.getBoolean("allowSsh") ?? false;
const region = (cfg.get("region") ?? "us-east-1") as aws.Region;

// Inject the model name into cloud-init at deploy time (a file read, not a shell-out).
const userData = fs.readFileSync("cloud-init.yaml", "utf8").replace(/__MODEL__/g, model);

// Region comes from config; credentials arrive ambiently from pulumi-idp/auth.
const provider = new aws.Provider("aws", { region });

// Most recent Ubuntu 24.04 LTS (amd64, hvm, gp3) published by Canonical.
const ubuntu = aws.ec2.getAmi({
 mostRecent: true,
 owners: ["099720109477"],
 filters: [
 { name: "name", values: ["ubuntu/images/hvm-ssd-gp3/ubuntu-noble-24.04-amd64-server-*"] },
 { name: "virtualization-type", values: ["hvm"] },
 ],
}, { provider });

const ingress: aws.types.input.ec2.SecurityGroupIngress[] = [{
 description: "Ollama HTTP API. NOTE: restrict cidrBlocks to your own range in production.",
 fromPort: 11434,
 toPort: 11434,
 protocol: "tcp",
 cidrBlocks: ["0.0.0.0/0"],
}];

if (allowSsh) {
 ingress.push({
 description: "SSH",
 fromPort: 22,
 toPort: 22,
 protocol: "tcp",
 cidrBlocks: ["0.0.0.0/0"],
 });
}

const sg = new aws.ec2.SecurityGroup("ollama", {
 description: "Ollama inferencing access",
 ingress,
 egress: [{
 description: "Allow all outbound",
 fromPort: 0,
 toPort: 0,
 protocol: "-1",
 cidrBlocks: ["0.0.0.0/0"],
 }],
}, {
 provider,
});

const server = new aws.ec2.Instance("ollama", {
 ami: ubuntu.then(a => a.id),
 instanceType: "g4dn.xlarge", // 1x NVIDIA T4
 vpcSecurityGroupIds: [sg.id],
 associatePublicIpAddress: true,
 userData, // plain text; the AWS provider base64-encodes it for you
 rootBlockDevice: {
 volumeSize: 40,
 volumeType: "gp3",
 },
 tags: { Name: "ollama" },
}, {
 provider,
});

export const publicIp = server.publicIp;
export const ollamaEndpoint = pulumi.interpolate`http://${publicIp}:11434`;
export const generateEndpoint = pulumi.interpolate`http://${publicIp}:11434/api/generate`;
export const tagsEndpoint = pulumi.interpolate`http://${publicIp}:11434/api/tags`;

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

const cfg = new pulumi.Config();
const model = cfg.get("model") ?? "qwen2.5:14b";
const allowSsh = cfg.getBoolean("allowSsh") ?? false;
const project = cfg.get("project");
const zone = cfg.get("zone") ?? "us-central1-a";

// Inject the model name into cloud-init at deploy time (a file read, not a shell-out).
const userData = fs.readFileSync("cloud-init.yaml", "utf8").replace(/__MODEL__/g, model);

// Latest Ubuntu 24.04 LTS amd64 image.
const ubuntu = gcp.compute.getImage({
 family: "ubuntu-2404-lts-amd64",
 project: "ubuntu-os-cloud",
});

// Network tag binds the firewall rule to this instance.
const networkTag = "ollama";

const firewall = new gcp.compute.Firewall("ollama-fw", {
 network: "default",
 project: project,
 // Inbound to Ollama from anywhere; restrict this CIDR for production.
 allows: allowSsh
 ? [{ protocol: "tcp", ports: ["11434"] }, { protocol: "tcp", ports: ["22"] }]
 : [{ protocol: "tcp", ports: ["11434"] }],
 sourceRanges: ["0.0.0.0/0"],
 targetTags: [networkTag],
});

const instance = new gcp.compute.Instance("ollama", {
 machineType: "n1-standard-4",
 zone: zone,
 project: project,
 tags: [networkTag],
 bootDisk: {
 initializeParams: {
 image: ubuntu.then(i => i.selfLink),
 size: 40,
 },
 },
 guestAccelerators: [{
 type: "nvidia-tesla-t4",
 count: 1,
 }],
 // GPUs cannot live-migrate, so host maintenance must terminate (and restart) the VM.
 scheduling: {
 onHostMaintenance: "TERMINATE",
 automaticRestart: true,
 },
 networkInterfaces: [{
 network: "default",
 accessConfigs: [{}], // an empty config requests an ephemeral public IP
 }],
 metadata: {
 "user-data": userData, // Ubuntu cloud-init reads this key, not startup-script
 },
}, {
 dependsOn: firewall,
});

export const publicIp = instance.networkInterfaces.apply(nics => nics[0].accessConfigs![0].natIp);
export const ollamaEndpoint = pulumi.interpolate`http://${publicIp}:11434`;
export const generateEndpoint = pulumi.interpolate`http://${publicIp}:11434/api/generate`;
export const tagsEndpoint = pulumi.interpolate`http://${publicIp}:11434/api/tags`;

import * as pulumi from "@pulumi/pulumi";
import * as resources from "@pulumi/azure-native/resources";
import * as network from "@pulumi/azure-native/network";
import * as compute from "@pulumi/azure-native/compute";
import * as random from "@pulumi/random";
import * as fs from "fs";

const cfg = new pulumi.Config();
const model = cfg.get("model") ?? "qwen2.5:14b";
const allowSsh = cfg.getBoolean("allowSsh") ?? false;
const location = cfg.get("location") ?? "eastus";

// Inject the model name into cloud-init at deploy time (a file read, not a shell-out).
const userData = fs.readFileSync("cloud-init.yaml", "utf8").replace(/__MODEL__/g, model);

const resourceGroup = new resources.ResourceGroup("ollama-rg", {
 location,
});

const vnet = new network.VirtualNetwork("ollama-vnet", {
 resourceGroupName: resourceGroup.name,
 addressSpace: { addressPrefixes: ["10.0.0.0/16"] },
});

const subnet = new network.Subnet("ollama-subnet", {
 resourceGroupName: resourceGroup.name,
 virtualNetworkName: vnet.name,
 addressPrefix: "10.0.1.0/24",
});

// Standard SKU public IPs use static allocation.
const publicIpAddress = new network.PublicIPAddress("ollama-pip", {
 resourceGroupName: resourceGroup.name,
 sku: { name: network.PublicIPAddressSkuName.Standard },
 publicIPAllocationMethod: network.IPAllocationMethod.Static,
});

// Azure permits all outbound by default, so only inbound rules are needed.
const nsg = new network.NetworkSecurityGroup("ollama-nsg", {
 resourceGroupName: resourceGroup.name,
 securityRules: [
 {
 name: "allow-ollama",
 priority: 1000,
 direction: network.SecurityRuleDirection.Inbound,
 access: network.SecurityRuleAccess.Allow,
 protocol: network.SecurityRuleProtocol.Tcp,
 sourcePortRange: "*",
 destinationPortRange: "11434",
 sourceAddressPrefix: "0.0.0.0/0", // prod: restrict to your client CIDR
 destinationAddressPrefix: "*",
 },
 ...(allowSsh ? [{
 name: "allow-ssh",
 priority: 1001,
 direction: network.SecurityRuleDirection.Inbound,
 access: network.SecurityRuleAccess.Allow,
 protocol: network.SecurityRuleProtocol.Tcp,
 sourcePortRange: "*",
 destinationPortRange: "22",
 sourceAddressPrefix: "0.0.0.0/0",
 destinationAddressPrefix: "*",
 }] : []),
 ],
});

const nic = new network.NetworkInterface("ollama-nic", {
 resourceGroupName: resourceGroup.name,
 networkSecurityGroup: { id: nsg.id },
 ipConfigurations: [{
 name: "ipconfig1",
 subnet: { id: subnet.id },
 publicIPAddress: { id: publicIpAddress.id },
 privateIPAllocationMethod: network.IPAllocationMethod.Dynamic,
 primary: true,
 }],
});

// Azure requires an admin credential even though we never log in. Generate one
// instead of hard-coding it; it stays a Pulumi secret and is never exported.
const adminPassword = new random.RandomPassword("ollama-admin-password", {
 length: 24,
 special: true,
 overrideSpecial: "!#$%*",
 minLower: 1,
 minUpper: 1,
 minNumeric: 1,
 minSpecial: 1, // Azure requires 3 of 4 character classes
});

const vm = new compute.VirtualMachine("ollama-vm", {
 resourceGroupName: resourceGroup.name,
 hardwareProfile: { vmSize: "Standard_NC4as_T4_v3" }, // 1x NVIDIA T4
 networkProfile: {
 networkInterfaces: [{ id: nic.id, primary: true }],
 },
 osProfile: {
 computerName: "ollama",
 adminUsername: "azureuser",
 adminPassword: adminPassword.result,
 customData: Buffer.from(userData).toString("base64"), // Azure wants base64
 linuxConfiguration: {
 disablePasswordAuthentication: false,
 },
 },
 storageProfile: {
 imageReference: {
 publisher: "Canonical",
 offer: "ubuntu-24_04-lts",
 sku: "server", // Gen2; NC4as_T4_v3 is a Gen2 size
 version: "latest",
 },
 osDisk: {
 name: "ollama-osdisk",
 createOption: "FromImage",
 diskSizeGB: 40,
 managedDisk: { storageAccountType: "StandardSSD_LRS" },
 },
 },
});

// A Standard/Static public IP is reserved at creation, so its address is known
// once the resource exists; no separate lookup needed.
export const publicIp = publicIpAddress.ipAddress.apply(ip => ip!);
export const ollamaEndpoint = pulumi.interpolate`http://${publicIp}:11434`;
export const generateEndpoint = pulumi.interpolate`http://${publicIp}:11434/api/generate`;
export const tagsEndpoint = pulumi.interpolate`http://${publicIp}:11434/api/tags`;

A few per-cloud details are worth calling out, since they are the places the “same program” abstraction leaks:

AWS is the shortest program, because the GPU comes with the instance shape: a g4dn.xlarge is a T4 box, so there is no separate accelerator to attach. The one thing to do before you deploy is raise the Running On-Demand G and VT instances vCPU quota in your region; a fresh account starts at zero, and pulumi up fails with VcpuLimitExceeded until you do.
Google Cloud attaches the GPU explicitly with guestAccelerators, and that brings the rule that trips people up: a GPU instance cannot live-migrate, so scheduling.onHostMaintenance must be "TERMINATE" or the apply is rejected. The cloud-init also has to ride on the user-data metadata key, not startup-script, and the empty accessConfigs: [{}] is what hands the box a public IP. T4 quota is also zero on a new project.
Azure is the longest listing, because the network is à la carte: the resource group, virtual network, subnet, public IP, security group, and NIC are each their own resource before you reach the VM. One detail surprises people: a Linux VM requires an admin credential even when you never log in, so the program generates a throwaway password with random.RandomPassword rather than committing one. The NC4as_T4_v3 is a compute GPU, so the standard server (CUDA) driver from the cloud-init is the right choice here; the GRID driver is only needed for GPU-accelerated visualization workloads.

The full programs, all three Pulumi.<cloud>.yaml files, and the shared cloud-init.yaml are in the companion repo:

github.com/dirien/fully-automated-ai-inference-pulumi

Run GPU inference across three clouds

Stand up an Ollama GPU box on AWS, Azure, or Google Cloud from one Pulumi program, with short-lived credentials brokered by Pulumi ESC and no static keys to rotate.

Get started

Deploying

Create a project, install the provider for your cloud, point the stack at pulumi-idp/auth, and deploy. For AWS:

mkdir ai-inference && cd ai-inference
pulumi new typescript
npm install @pulumi/aws

Drop the AWS listing into index.ts, copy the cloud-init.yaml shown earlier into the same directory (or grab it from the companion repo), point the stack at the auth environment, and set your region:

pulumi stack init aws
# add `environment: [pulumi-idp/auth]` to Pulumi.aws.yaml (shown above)
pulumi config set region us-east-1
pulumi config set model qwen2.5:14b
pulumi up

The other two clouds are the same flow with a different provider package and a couple of config keys: npm install @pulumi/gcp with pulumi config set project <your-project-id> and pulumi config set zone us-central1-a, or npm install @pulumi/azure-native @pulumi/random with pulumi config set location eastus.

The slow part is the GPU box: it boots, installs the driver, reboots, installs Ollama, and pulls the model, all without you. Depending on the instance, the region, and the model size, plan on roughly 10 to 15 minutes before the endpoint answers. When pulumi up finishes you get the endpoints straight back as stack outputs:

Outputs:
 generateEndpoint: "http://<public-ip>:11434/api/generate"
 ollamaEndpoint : "http://<public-ip>:11434"
 publicIp : "<public-ip>"
 tagsEndpoint : "http://<public-ip>:11434/api/tags"

Testing the inference server

pulumi up returns as soon as the infrastructure exists, which is before the model has finished downloading. This is exactly where Terraform reached for that null_resource loop, and where Pulumi hands you a URL instead. To check whether the model is ready, ask Ollama what it has loaded:

curl -s $(pulumi stack output tagsEndpoint) | grep -q "qwen2.5:14b" && echo "ready" || echo "still pulling"

Once it reports ready, send it a prompt. This is the same request the Akamai post makes, pointed at your generateEndpoint output:

curl -s $(pulumi stack output generateEndpoint) -d '{
 "model": "qwen2.5:14b",
 "system": "Answer every question with a three-line poem.",
 "prompt": "Why is the sky blue?",
 "stream": false
}'

The first call is slower, because Ollama loads the model into GPU memory before it answers. Every call after that is fast, since OLLAMA_KEEP_ALIVE=-1 keeps it resident:

{
 "model": "qwen2.5:14b",
 "response": "Sunlight scatters, short waves fly,\nBlue light paints the open sky,\nViolet fades as day drifts by.",
 "done": true
}

When you are done, take it all down with one command, so the GPU stops billing:

pulumi destroy

Cost

A GPU instance is the whole bill, and you pay by the hour whether the model is busy or idle. The numbers below are rough on-demand rates for a single T4-class box left running 24/7; in practice you spin it up, use it, and pulumi destroy it, so what you actually pay tracks the hours it stays up.

Cloud	Instance	GPU	~Hourly	~Monthly (24/7)
AWS	`g4dn.xlarge`	1× T4 (16 GB)	~$0.53	~$384
Azure	`Standard_NC4as_T4_v3`	1× T4 (16 GB)	~$0.53	~$384
Google Cloud	`n1-standard-4` + 1× T4	1× T4 (16 GB)	~$0.54	~$394

These are on-demand Linux rates in a cheap US region (us-east-1, eastus, us-central1) as of mid-2026, and the GPU dominates the bill. Spot or preemptible capacity cuts it sharply if your workload tolerates interruption (often 60 to 70 percent off), Google Cloud’s sustained-use discount trims an always-on instance on its own, and the 40 GB disk adds only a few dollars a month.

A GPU box left running overnight is the expensive mistake here. Because the whole stack is declarative, the safe habit is cheap: pulumi destroy when you stop using it, pulumi up when you need it back. The state and config are version-controlled, so standing it up again is one command, not a rebuild.

Security considerations

The architecture in this post matches the Akamai original on purpose, which means it carries the same caveat: Ollama is exposed over plain HTTP on a port open to the entire internet. That is fine for a demo on a box you tear down the same day. It is not fine for anything that outlives the afternoon, and self-hosted AI endpoints get found fast: scanners like Shodan enumerate a freshly exposed one within hours, and an open Ollama instance is free compute for whoever finds it first.

The credential side, though, is genuinely better than a static-token setup, and that is the part worth keeping. There is no long-lived cloud key in the program, in your shell, or in CI; every deploy gets short-lived credentials minted through pulumi-idp/auth and thrown away when it finishes.

Concern	Akamai/Terraform demo	This deployment
Cloud credentials	Static PAT in an env var	OIDC login, short-lived, via `pulumi-idp/auth`
Inbound exposure	Port 11434 open to `0.0.0.0/0`	Same by default; one config flag scopes the CIDR
Transport	Plain HTTP	Plain HTTP (front with TLS for real use)
Readiness wait	`null_resource` + `local-exec` shell loop	A runtime `curl`, no resource

My recommendations for taking this past a demo:

Scope the inbound rule to your own CIDR instead of 0.0.0.0/0; the allowSsh flag in the program is the pattern to copy for the Ollama port
Put a reverse proxy with TLS in front of Ollama, or keep the box off the public internet entirely and reach it over a private network or a Tailscale tailnet, the way I did for the Hermes agent
Keep credentials on OIDC through ESC; never fall back to a static key to “just get it working”
Treat the box as disposable, and pulumi destroy it when you are not using it, which shrinks both the bill and the attack window

What’s next?

The program is a foundation, and the interesting work is what you layer on once a model is a pulumi up away:

Lock it down. Scope the firewall, add TLS, or move the box behind a private network so the endpoint is not on the public internet at all.
Scale the model to the GPU. qwen2.5:14b on a T4 is the entry point. Bigger models want more memory, which means an A10G, an L4, or an A100, and the only change in the program is the instance type and the model value.
Swap the serving engine. Ollama is the simplest thing that works. For higher throughput, the same shape holds with vLLM in place of Ollama in the cloud-init.
Generate the next one. Pulumi Neo can take a target like “a GPU inference box on Azure behind a private endpoint” and produce a first draft of the program, which you then review in a PR like any other change.

Conclusion

Declaring an AI inference server as code buys you the same thing it buys for any other infrastructure: you can reproduce it on any of the three clouds, version-control it, and tear it down with a single pulumi destroy. Porting the Akamai project made the contrast sharp. The credentials moved from a static token to an OIDC login that leaves nothing behind, and the readiness wait disappeared entirely once you stop treating a runtime check as a resource.

That is the line worth carrying to the next thing you deploy. Not every step in a runbook is a resource. A GPU box and a firewall rule are; waiting for a download to finish is not. Draw that line first, and the program gets shorter on its own.

If you run into issues or have questions, drop by the Pulumi Community Slack or GitHub Discussions. New to Pulumi? Get started here.

Deploy a Private Hermes Agent on Render Securely with Pulumi, Modal, and Tailscale

Engin Diri — Wed, 24 Jun 2026 00:00:00 +0000

Personal AI agents had their breakout this year. OpenClaw crossed 100,000 GitHub stars within months of launching, and self-hosting your own assistant went from a hobbyist trick to something a lot of developers actually do. I wrote up how to deploy that lobster to AWS or Hetzner back when it was everywhere.

The one people are switching to now is Hermes, the open-source runtime from Nous Research, and it caught on just as quickly. The reason shows up in every “I ditched OpenClaw for Hermes” thread: it actually learns, building up memory and writing its own skills as it goes instead of running off a static, human-written list.

Here is the part the launch videos skip. Hermes writes and runs its own code, with no human approving the commands. A model that can write code will eventually write a bad one, and the only thing between that command and your credentials is the sandbox it runs in. That is the box you do not want on the public internet. Researchers found 175,000 exposed Ollama servers sitting open in early 2026, and attackers hijack the ones they find for compute. The fix is not a better lock on the front door. It is to have no front door at all.

So this post deploys a private Hermes agent as one Pulumi program across Render, Modal, and Tailscale. The agent and its chat UI run as Render private services with no public URL, Tailscale puts the UI on your tailnet, and Modal runs the agent’s code in throwaway sandboxes. One pulumi up to stand it up, one pulumi destroy to tear it down, around $50 a month. No Makefile, no CLI escape hatches, and an honest look at the few places “nothing on the public internet” still leaks.

What is Hermes?

Hermes is the open-source, MIT-licensed agent runtime from Nous Research. It runs continuously on a server rather than living in a browser tab, and you talk to it through a chat UI or a messaging platform like Telegram, Discord, Slack, or Signal. A few things make it more than a chatbot:

It is model-agnostic. You point it at any provider. This deployment uses OpenRouter, one key that fronts 400-plus models across providers, with automatic failover when one is down.
It remembers across restarts. Memory persists on disk, so it builds up context over time instead of resetting every session.
It writes its own skills. When it works through a task, it can save that approach as a reusable skill and reach for it next time.
It schedules itself. A built-in cron runs automations on a schedule, driven in plain language.
It runs code in a sandbox. When the agent needs to execute code, it hands that off to an isolated, ephemeral container instead of running it next to its own process.

The difference from a cloud-hosted assistant is the usual self-hosting trade: it runs on your infrastructure with your keys, and your conversation history and memory stay on your disk.

“Hermes” here is the agent runtime from Nous Research, not the Hermes family of language models that share the name. The agent is model-agnostic, and the model it talks to is a separate choice you make through OpenRouter.

Prerequisites

Before getting started, ensure you have:

Pulumi CLI installed and configured
A Pulumi Cloud account
A Render account, an API key, and your workspace owner ID
A Modal account and a token pair (token ID and secret)
An OpenRouter API key with credit on the account
A container registry you can push to; this post uses GitHub Container Registry (a GHCR username and token)
Docker running locally (the image build rides on a local buildx engine), or a Docker-enabled CI runner
A Tailscale account with HTTPS enabled and a reusable auth key
Node.js 18+ (for TypeScript) or Python 3.9+ (for Python), depending on the language you pick

This guide routes models through OpenRouter, but Hermes works with other providers too. The model is just a routing string you pass (gpt-5.5 here), so any model OpenRouter supports works by changing that one value.

Understanding the Hermes architecture

Strip away the dashboard clicks and the architecture is four pieces. One rule governs all of them: what the public internet is allowed to touch.

flowchart LR
User([Your devices]) -->|"tailnet (WireGuard)"| TS["Tailscale<br/>private mesh"]
TS -->|"open-webui.&lt;tailnet&gt;.ts.net"| WebUI["Open WebUI<br/>(Render private service,<br/>joined to your tailnet)"]
WebUI -->|"private network<br/>&lt;hermes-slug&gt;:8642"| Hermes["Hermes gateway<br/>(Render private service)"]
Hermes -->|"Modal SDK at runtime"| Modal["Modal sandbox<br/>isolated code execution"]
Hermes -->|model calls| OR["OpenRouter"]

Component	Port	Description
Hermes gateway	8642	Holds secrets and memory, talks to the model, creates Modal sandboxes. The most dangerous box, so it has no public URL.
Open WebUI	8080	The chat front end. Joins your tailnet and reaches Hermes over Render’s private network.
Modal sandbox	-	Isolated, ephemeral container for running the agent’s code.
Tailscale	-	A private WireGuard mesh that makes the UI reachable to your devices only.

The agent that can run code and read secrets is never routable from the internet, and neither is the UI in front of it. There is no inbound ingress on any box (the outbound calls to the model, to Modal, and to the image registry still cross the internet, as they have to). Expressing “which box can reach which” in code is what makes the boundary auditable: the rule lives in the program rather than in a dashboard.

The four pieces split cleanly in two: two you declare as resources, and two you hand a credential and let run.

Layer	How you provision it	Status
Render services, disks, secrets	official `render-oss` Terraform provider, bridged	Declarative, via one `pulumi package add`.
Container images	`@pulumi/docker-build`	Built and pushed during `pulumi up`. No `docker` CLI.
Modal sandboxes	nothing	No Terraform provider exists. A runtime credential.
Tailnet access (Tailscale)	nothing	No provider needed. A runtime credential, like Modal.

Two of these four layers are credentials, not resources. That distinction often gets missed, and it is worth getting right: a provider can only manage what it can provision, and spinning up a Modal sandbox is a runtime act, not a provisioned resource. We come back to it at each layer.

Setting up ESC for secrets management

Deploying Hermes means handling a pile of credentials: a Render API key, registry credentials, the OpenRouter key, the Modal token pair, and the Tailscale auth key. You don’t want these hardcoded or scattered across environment variables. Pulumi ESC (Environments, Secrets, and Configuration) stores them securely and passes them directly to your Pulumi program.

Create a new ESC environment:

pulumi env init <your-org>/hermes-secrets

Add your secrets to the environment:

values:
 renderApiKey:
 fn::secret: "rnd_xxxxx"
 renderOwnerId: "tea-xxxxx"
 ghcrUser: "your-github-username"
 ghcrToken:
 fn::secret: "ghp_xxxxx"
 openrouterApiKey:
 fn::secret: "sk-or-xxxxx"
 modalTokenId:
 fn::secret: "ak-xxxxx"
 modalTokenSecret:
 fn::secret: "as-xxxxx"
 tailscaleAuthKey:
 fn::secret: "tskey-auth-xxxxx"
 tailnetDnsName: "tailxxxxx.ts.net"
 pulumiConfig:
 renderApiKey: ${renderApiKey}
 ownerId: ${renderOwnerId}
 ghcrUser: ${ghcrUser}
 ghcrToken: ${ghcrToken}
 openrouterApiKey: ${openrouterApiKey}
 modalTokenId: ${modalTokenId}
 modalTokenSecret: ${modalTokenSecret}
 tailscaleAuthKey: ${tailscaleAuthKey}
 tailnetDnsName: ${tailnetDnsName}

To find your tailnet DNS name, go to the Tailscale admin console, look under the DNS section, and find your tailnet name (e.g., tailxxxxx.ts.net). This is the domain suffix used for all machines in your Tailscale network.

Then create a Pulumi.dev.yaml file in your project to reference the environment:

environment:
 - <your-org>/hermes-secrets

This keeps your secrets out of your codebase and hands them to the program at deploy time. The Modal token pair and the Tailscale auth key never become resources; they ride straight through as encrypted env vars on the services that need them.

Generating the Render SDK

Render has no first-party Pulumi provider. What it has is an official, maintained Terraform provider, and Pulumi can turn any Terraform provider into a typed local SDK with Any Terraform Provider:

pulumi package add terraform-provider render-oss/render 1.8.0

That one command generates a render SDK you import like any other package, in whatever language your stack is written in. There is no published @pulumi/render package and no vendor to wait on.

This is also where the provider map shows its edges. The bridge wraps a Terraform provider that already exists, so it works for Render. But Modal has no Terraform provider anywhere, so pulumi package add terraform-provider modal-labs/modal has nothing to fetch. That is not a gap to work around. Modal is not a provisioned resource here; Hermes creates sandboxes at runtime through the Modal SDK, and Pulumi’s only job is to hold the token pair and hand it over. Tailscale lands in the same bucket: a Tailscale provider exists, but it manages your tailnet’s settings, not the act of putting a container on the network, which is a runtime job done inside the image.

Securing with Tailscale

The usual way to make a self-hosted UI reachable is to give it a public hostname and put an identity gate in front: an SSO provider, an access policy, a public DNS record, and a certificate to keep renewing. Tailscale collapses all of it into nothing you declare. There is no gate to bolt in front of a public URL, because there is no public URL. Open WebUI joins your tailnet and answers only to your own devices.

This is a stronger position than a public UI behind a login. Because there is no public URL, there is no login to harden and no certificate to renew, and Open WebUI answers only to your own devices.

Tailscale lives in the Open WebUI image rather than the Pulumi program. The image adds Tailscale and an entrypoint that brings up tailscaled in userspace mode (a container has no /dev/net/tun), joins your tailnet, and runs tailscale serve to expose Open WebUI on it. serve publishes over HTTPS to authenticated members of your tailnet only, where its sibling tailscale funnel would put the same port on the public internet, the one thing this design avoids.

FROM ghcr.io/open-webui/open-webui:main-slim
RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates \
 && curl -fsSL https://tailscale.com/install.sh | sh
COPY entrypoint.sh /usr/local/bin/ts-entrypoint
ENTRYPOINT ["/usr/local/bin/ts-entrypoint"]

#!/usr/bin/env bash
set -e
PORT="${PORT:-8080}"
mkdir -p /app/backend/data/tailscale
# Userspace networking: a container has no /dev/net/tun. Keep node state on the disk
# so it survives restarts, and accept-dns=false so Render's DNS still resolves the
# private Hermes hostname.
tailscaled --tun=userspace-networking --statedir=/app/backend/data/tailscale &
n=0
until tailscale up --authkey="${TS_AUTHKEY}" --hostname="${TS_HOSTNAME}" --accept-dns=false; do
 n=$((n + 1)); [ "${n}" -ge 30 ] && { echo "tailnet join failed; check TS_AUTHKEY"; exit 1; }
 sleep 2
done
tailscale serve --bg "${PORT}" # serve Open WebUI on the tailnet over HTTPS
cd /app/backend && exec bash start.sh

The TS_AUTHKEY env var on the service, pulled from ESC, is the only thing Pulumi contributes; everything else is the image doing its own networking.

There is one prerequisite, the same one any Tailscale node needs for serve: enable HTTPS for your tailnet once in the admin console so it can get a certificate. Use a reusable auth key, since the service re-authenticates on every redeploy, and the join loop has a ceiling so a dead key fails the deploy in a minute instead of hanging it.

To generate the reusable auth key:

Go to the Tailscale admin console.
Click Generate auth key.
Enable Reusable, since the service re-authenticates on every redeploy.
Copy the key into your ESC environment as tailscaleAuthKey.

Deploying the agent

This is the part a Makefile usually handles. Two private services, two disks, every secret an encrypted env var, and both images built and pushed during the same pulumi up that creates the services. No CLI runs anywhere, though the build still rides on a local Docker engine through buildx: the docker call is gone, the daemon it talks to is not, so pulumi up needs Docker running.

Create a new Pulumi project (pick the language you prefer; the companion repo has all three):

mkdir hermes-agent-pulumi && cd hermes-agent-pulumi
pulumi new typescript

Install the dependencies and generate the Render SDK:

npm install @pulumi/docker-build @pulumi/random
pulumi package add terraform-provider render-oss/render 1.8.0

Both services need the 2 GB Standard plan. The gateway and Open WebUI each exhaust memory on the 512 MB Starter and OOM on boot.

Two facts make this clean. Render env var values are encrypted at rest, so a secret is only an env var, with no separate resource. And @pulumi/docker-build builds and pushes an image through an embedded buildx during pulumi up, so the image pipeline is declarative too. Render then pulls the pushed image by digest.

The complete program

Hermes comes first: a private Render service with no public URL, a disk for its memory, and every secret as an encrypted env var. The shared bearer key is generated in state with random.RandomBytes, the clean replacement for openssl rand -base64 32; the Modal token pair and the OpenRouter key come from config or Pulumi ESC. Render has no port field, so Hermes binds 0.0.0.0:8642 and Open WebUI reaches it at the service’s read-only slug. Open WebUI is almost the mirror image, private too, except its image joins your tailnet (the tailscaled entrypoint from the previous section) and it carries the operational env vars that keep it lean: no local embedding models, and ENABLE_PERSISTENT_CONFIG=false so your config always wins over a stale copy in its database. One render.Provider carries your renderApiKey and ownerId into every Render resource.

Here is the whole program, copy-paste ready as your index.ts (or __main__.py, or Pulumi.yaml):

import * as pulumi from "@pulumi/pulumi";
import * as dockerbuild from "@pulumi/docker-build";
import * as random from "@pulumi/random";
// Local SDK generated by: pulumi package add terraform-provider render-oss/render 1.8.0
// (no @pulumi/render is published; the SDK is bridged from the official Render provider).
import * as render from "@pulumi/render";

const cfg = new pulumi.Config();

// ---------------------------------------------------------------------------
// Configuration. Non-secret values via `pulumi config set`, secrets via
// `pulumi config set --secret` or a Pulumi ESC environment (see README).
// The Render provider reads renderApiKey/renderOwnerId (or RENDER_API_KEY/RENDER_OWNER_ID).
// ---------------------------------------------------------------------------
const region = cfg.get("renderRegion") ?? "oregon";
const modelDefault = cfg.get("modelDefault") ?? "gpt-5.5";

// Container registry the images are pushed to and Render pulls from (GHCR here).
const ghcrUser = cfg.require("ghcrUser");
const ghcrToken = cfg.requireSecret("ghcrToken"); // GHCR PAT with write:packages

// Long-lived secrets supplied by you (dashboard-minted). Hold in config or ESC.
const modalTokenId = cfg.requireSecret("modalTokenId");
const modalTokenSecret = cfg.requireSecret("modalTokenSecret");
const openrouterApiKey = cfg.requireSecret("openrouterApiKey");

// Tailscale: the only "gateway". Open WebUI joins your tailnet and is reachable
// at https://<hostname>.<tailnet>.ts.net by your devices only — never public.
// Both values are already in your ESC. Enable HTTPS once in the Tailscale admin console.
const tailscaleAuthKey = cfg.requireSecret("tailscaleAuthKey");
const tailnetDnsName = cfg.require("tailnetDnsName"); // e.g. tailc6fb4e.ts.net
const webuiHostname = "open-webui";
const webuiTailnetUrl = `https://${webuiHostname}.${tailnetDnsName}`;

// Render provider auth (from ESC: pulumiConfig.renderApiKey / pulumiConfig.renderOwnerId).
const renderProvider = new render.Provider("render", {
 apiKey: cfg.requireSecret("renderApiKey"),
 ownerId: cfg.require("renderOwnerId"),
});

// ---------------------------------------------------------------------------
// Secrets generated in state (the in-IaC replacement for `openssl rand -base64 32`).
// The shared bearer authenticates Open WebUI -> Hermes; it lands on both services.
// ---------------------------------------------------------------------------
const sharedKey = new random.RandomBytes("hermes-shared-key", { length: 32 });
const webuiSecretKey = new random.RandomBytes("webui-secret-key", { length: 32 });

// ---------------------------------------------------------------------------
// Build and push both images during `pulumi up` (no docker CLI; the provider
// embeds buildx). Render then pulls them by their digest-pinned ref.
// ---------------------------------------------------------------------------
const registryAuth = [{ address: "ghcr.io", username: ghcrUser, password: ghcrToken }];

const hermesImage = new dockerbuild.Image("hermes-image", {
 context: { location: "./hermes" },
 dockerfile: { location: "./hermes/Dockerfile" },
 platforms: ["linux/amd64"],
 tags: [pulumi.interpolate`ghcr.io/${ghcrUser}/hermes-agent:latest`],
 push: true,
 registries: registryAuth,
});

const webuiImage = new dockerbuild.Image("webui-image", {
 context: { location: "./openwebui" },
 dockerfile: { location: "./openwebui/Dockerfile" },
 platforms: ["linux/amd64"],
 tags: [pulumi.interpolate`ghcr.io/${ghcrUser}/open-webui:latest`],
 push: true,
 registries: registryAuth,
});

// Credential Render uses to pull the private GHCR images.
const ghcrCredential = new render.RegistryCredential("ghcr", {
 name: "ghcr",
 registry: "GITHUB",
 username: ghcrUser,
 authToken: ghcrToken,
}, { provider: renderProvider });

// ---------------------------------------------------------------------------
// Hermes: a PRIVATE Render service. No public URL; reachable only over Render's
// private network. A disk holds its memory and workspace. Env values are
// encrypted at rest, which is how secrets ride on Render (no separate flag).
// ---------------------------------------------------------------------------
const hermes = new render.PrivateService("hermes-agent", {
 name: "hermes-agent",
 plan: "standard", // 2 GB; the gateway OOMs on starter's 512 MB
 region: region,
 runtimeSource: {
 // Render wants the bare repo in imageUrl; the tag/digest go in their own field.
 image: {
 imageUrl: pulumi.interpolate`ghcr.io/${ghcrUser}/hermes-agent`,
 digest: hermesImage.digest,
 registryCredentialId: ghcrCredential.id,
 },
 },
 disk: { name: "hermes-data", mountPath: "/opt/data", sizeGb: 5 },
 envVars: {
 PORT: { value: "8642" },
 API_SERVER_ENABLED: { value: "true" },
 API_SERVER_HOST: { value: "0.0.0.0" },
 API_SERVER_PORT: { value: "8642" },
 API_SERVER_MODEL_NAME: { value: modelDefault },
 // Auto-approve the agent's shell/terminal hooks (no TTY in a container),
 // so it can run code in the Modal sandbox without an interactive prompt.
 HERMES_ACCEPT_HOOKS: { value: "1" },
 // Secrets (encrypted at rest on Render):
 API_SERVER_KEY: { value: sharedKey.base64 },
 OPENROUTER_API_KEY: { value: openrouterApiKey },
 // Modal is a runtime credential, not a provisioned resource: Hermes creates
 // sandboxes at runtime with this token pair. No Modal provider, no Modal CLI.
 MODAL_TOKEN_ID: { value: modalTokenId },
 MODAL_TOKEN_SECRET: { value: modalTokenSecret },
 },
}, { provider: renderProvider });

// Open WebUI reaches Hermes at its Render-assigned internal hostname (the read-only
// slug), not the bare service name. Same region + same workspace share the network.
const hermesApiBaseUrl = pulumi.interpolate`http://${hermes.slug}:8642/v1`;

// ---------------------------------------------------------------------------
// Open WebUI: also a PRIVATE Render service, but the container joins your tailnet
// (tailscaled in userspace + `tailscale serve`), so you reach it at
// https://open-webui.<tailnet>.ts.net from your devices. Never public; the gate
// is tailnet membership. It still reaches Hermes over Render's private network.
// ---------------------------------------------------------------------------
const webui = new render.PrivateService("open-webui", {
 name: "open-webui",
 plan: "standard", // 2 GB; Open WebUI OOMs on starter's 512 MB
 region: region, // must match Hermes for private networking
 runtimeSource: {
 image: {
 imageUrl: pulumi.interpolate`ghcr.io/${ghcrUser}/open-webui`,
 digest: webuiImage.digest,
 registryCredentialId: ghcrCredential.id,
 },
 },
 disk: { name: "openwebui-data", mountPath: "/app/backend/data", sizeGb: 5 },
 envVars: {
 PORT: { value: "8080" }, // tailscale serve points at this; Open WebUI binds it
 OPENAI_API_BASE_URL: { value: hermesApiBaseUrl },
 ENABLE_OPENAI_API: { value: "true" },
 ENABLE_OLLAMA_API: { value: "false" },
 DEFAULT_MODELS: { value: modelDefault },
 WEBUI_AUTH: { value: "true" },
 WEBUI_URL: { value: webuiTailnetUrl },
 // Reached only over the tailnet, so the first sign-up is the admin.
 ENABLE_LOGIN_FORM: { value: "true" },
 ENABLE_SIGNUP: { value: "true" },
 DEFAULT_USER_ROLE: { value: "admin" },
 // Always apply env config; otherwise Open WebUI persists the first run's config
 // to its DB and ignores later changes.
 ENABLE_PERSISTENT_CONFIG: { value: "false" },
 // Don't load local embedding/RAG models (a big memory saver; the agent is the brain).
 RAG_EMBEDDING_ENGINE: { value: "openai" },
 BYPASS_EMBEDDING_AND_RETRIEVAL: { value: "true" },
 OFFLINE_MODE: { value: "true" },
 HF_HUB_OFFLINE: { value: "1" },
 // Secrets (encrypted at rest):
 OPENAI_API_KEY: { value: sharedKey.base64 }, // shared bearer to call Hermes
 WEBUI_SECRET_KEY: { value: webuiSecretKey.base64 },
 // Tailscale joins this container to your tailnet and serves Open WebUI on it.
 TS_AUTHKEY: { value: tailscaleAuthKey },
 TS_HOSTNAME: { value: webuiHostname },
 },
}, { dependsOn: hermes, provider: renderProvider });

export const hermesInternalUrl = hermesApiBaseUrl;
// Open this from any device on your tailnet:
export const openWebUiTailnetUrl = webuiTailnetUrl;

import pulumi
import pulumi_docker_build as docker_build
import pulumi_random as random

# Local SDK generated by: pulumi package add terraform-provider render-oss/render 1.8.0
# (no pulumi_render is published; the SDK is bridged from the official Render provider).
import pulumi_render as render

cfg = pulumi.Config()

# ---------------------------------------------------------------------------
# Configuration. Non-secret values via `pulumi config set`, secrets via
# `pulumi config set --secret` or a Pulumi ESC environment (see README).
# The Render provider reads renderApiKey/renderOwnerId (or RENDER_API_KEY/RENDER_OWNER_ID).
# ---------------------------------------------------------------------------
region = cfg.get("renderRegion") or "oregon"
model_default = cfg.get("modelDefault") or "gpt-5.5"

# Container registry the images are pushed to and Render pulls from (GHCR here).
ghcr_user = cfg.require("ghcrUser")
ghcr_token = cfg.require_secret("ghcrToken") # GHCR PAT with write:packages

# Long-lived secrets supplied by you (dashboard-minted). Hold in config or ESC.
modal_token_id = cfg.require_secret("modalTokenId")
modal_token_secret = cfg.require_secret("modalTokenSecret")
openrouter_api_key = cfg.require_secret("openrouterApiKey")

# Tailscale: the only "gateway". Open WebUI joins your tailnet and is reachable
# at https://<hostname>.<tailnet>.ts.net by your devices only -- never public.
# Enable HTTPS once in the Tailscale admin console so `tailscale serve` can get a cert.
tailscale_auth_key = cfg.require_secret("tailscaleAuthKey")
tailnet_dns_name = cfg.require("tailnetDnsName") # e.g. tailc6fb4e.ts.net
webui_hostname = "open-webui"
webui_tailnet_url = f"https://{webui_hostname}.{tailnet_dns_name}"

# Render provider auth (from ESC: pulumiConfig.renderApiKey / pulumiConfig.renderOwnerId).
render_provider = render.Provider(
 "render",
 api_key=cfg.require_secret("renderApiKey"),
 owner_id=cfg.require("renderOwnerId"),
)

# ---------------------------------------------------------------------------
# Secrets generated in state (the in-IaC replacement for `openssl rand -base64 32`).
# The shared bearer authenticates Open WebUI -> Hermes; it lands on both services.
# ---------------------------------------------------------------------------
shared_key = random.RandomBytes("hermes-shared-key", length=32)
webui_secret_key = random.RandomBytes("webui-secret-key", length=32)

# ---------------------------------------------------------------------------
# Build and push both images during `pulumi up` (no docker CLI; the provider
# embeds buildx). Render then pulls them by their digest-pinned ref.
# ---------------------------------------------------------------------------
registry_auth = [{"address": "ghcr.io", "username": ghcr_user, "password": ghcr_token}]

hermes_image = docker_build.Image(
 "hermes-image",
 context={"location": "./hermes"},
 dockerfile={"location": "./hermes/Dockerfile"},
 platforms=["linux/amd64"],
 tags=[pulumi.Output.concat("ghcr.io/", ghcr_user, "/hermes-agent:latest")],
 push=True,
 registries=registry_auth,
)

webui_image = docker_build.Image(
 "webui-image",
 context={"location": "./openwebui"},
 dockerfile={"location": "./openwebui/Dockerfile"},
 platforms=["linux/amd64"],
 tags=[pulumi.Output.concat("ghcr.io/", ghcr_user, "/open-webui:latest")],
 push=True,
 registries=registry_auth,
)

# Credential Render uses to pull the private GHCR images.
ghcr_credential = render.RegistryCredential(
 "ghcr",
 name="ghcr",
 registry="GITHUB",
 username=ghcr_user,
 auth_token=ghcr_token,
 opts=pulumi.ResourceOptions(provider=render_provider),
)

# ---------------------------------------------------------------------------
# Hermes: a PRIVATE Render service. No public URL; reachable only over Render's
# private network. A disk holds its memory and workspace. Env values are
# encrypted at rest, which is how secrets ride on Render (no separate flag).
# ---------------------------------------------------------------------------
hermes = render.PrivateService(
 "hermes-agent",
 name="hermes-agent",
 plan="standard", # 2 GB; the gateway OOMs on starter's 512 MB
 region=region,
 runtime_source={
 "image": {
 "image_url": pulumi.Output.concat("ghcr.io/", ghcr_user, "/hermes-agent"),
 "digest": hermes_image.digest,
 "registry_credential_id": ghcr_credential.id,
 },
 },
 disk={"name": "hermes-data", "mount_path": "/opt/data", "size_gb": 5},
 env_vars={
 "PORT": {"value": "8642"},
 "API_SERVER_ENABLED": {"value": "true"},
 "API_SERVER_HOST": {"value": "0.0.0.0"},
 "API_SERVER_PORT": {"value": "8642"},
 "API_SERVER_MODEL_NAME": {"value": model_default},
 # Auto-approve the agent's shell/terminal hooks (no TTY in a container).
 "HERMES_ACCEPT_HOOKS": {"value": "1"},
 # Secrets (encrypted at rest on Render):
 "API_SERVER_KEY": {"value": shared_key.base64},
 "OPENROUTER_API_KEY": {"value": openrouter_api_key},
 # Modal is a runtime credential: Hermes creates sandboxes at runtime with this pair.
 "MODAL_TOKEN_ID": {"value": modal_token_id},
 "MODAL_TOKEN_SECRET": {"value": modal_token_secret},
 },
 opts=pulumi.ResourceOptions(provider=render_provider),
)

# Open WebUI reaches Hermes at its Render-assigned internal hostname (the read-only slug).
hermes_api_base_url = pulumi.Output.concat("http://", hermes.slug, ":8642/v1")

# ---------------------------------------------------------------------------
# Open WebUI: also a PRIVATE Render service, but the container joins your tailnet
# (tailscaled in userspace + `tailscale serve`), so you reach it at
# https://open-webui.<tailnet>.ts.net from your devices. Never public.
# ---------------------------------------------------------------------------
webui = render.PrivateService(
 "open-webui",
 name="open-webui",
 plan="standard", # 2 GB; Open WebUI OOMs on starter's 512 MB
 region=region, # must match Hermes for private networking
 runtime_source={
 "image": {
 "image_url": pulumi.Output.concat("ghcr.io/", ghcr_user, "/open-webui"),
 "digest": webui_image.digest,
 "registry_credential_id": ghcr_credential.id,
 },
 },
 disk={"name": "openwebui-data", "mount_path": "/app/backend/data", "size_gb": 5},
 env_vars={
 "PORT": {"value": "8080"}, # tailscale serve points at this; Open WebUI binds it
 "OPENAI_API_BASE_URL": {"value": hermes_api_base_url},
 "ENABLE_OPENAI_API": {"value": "true"},
 "ENABLE_OLLAMA_API": {"value": "false"},
 "DEFAULT_MODELS": {"value": model_default},
 "WEBUI_AUTH": {"value": "true"},
 "WEBUI_URL": {"value": webui_tailnet_url},
 # Reached only over the tailnet, so the first sign-up is the admin.
 "ENABLE_LOGIN_FORM": {"value": "true"},
 "ENABLE_SIGNUP": {"value": "true"},
 "DEFAULT_USER_ROLE": {"value": "admin"},
 # Always apply env config; otherwise Open WebUI persists the first run's config.
 "ENABLE_PERSISTENT_CONFIG": {"value": "false"},
 # Don't load local embedding/RAG models (a big memory saver; the agent is the brain).
 "RAG_EMBEDDING_ENGINE": {"value": "openai"},
 "BYPASS_EMBEDDING_AND_RETRIEVAL": {"value": "true"},
 "OFFLINE_MODE": {"value": "true"},
 "HF_HUB_OFFLINE": {"value": "1"},
 # Secrets (encrypted at rest):
 "OPENAI_API_KEY": {"value": shared_key.base64},
 "WEBUI_SECRET_KEY": {"value": webui_secret_key.base64},
 # Tailscale joins this container to your tailnet and serves Open WebUI on it.
 "TS_AUTHKEY": {"value": tailscale_auth_key},
 "TS_HOSTNAME": {"value": webui_hostname},
 },
 opts=pulumi.ResourceOptions(depends_on=[hermes], provider=render_provider),
)

pulumi.export("hermesInternalUrl", hermes_api_base_url)
# Open this from any device on your tailnet:
pulumi.export("openWebUiTailnetUrl", webui_tailnet_url)

name: hermes-agent-pulumi
runtime: yaml
description: Deploy a Hermes agent (Render + Modal + Tailscale) as one declarative Pulumi program.

# The Render SDK is bridged from the official Terraform provider. Run once:
# pulumi package add terraform-provider render-oss/render 1.8.0
# Then `pulumi install` regenerates it on a fresh checkout.
packages:
 render:
 source: terraform-provider
 version: 1.1.4
 parameters:
 - render-oss/render
 - 1.8.0

config:
 renderRegion:
 type: string
 default: oregon
 modelDefault:
 type: string
 default: gpt-5.5
 ghcrUser:
 type: string
 ghcrToken:
 type: string
 secret: true
 modalTokenId:
 type: string
 secret: true
 modalTokenSecret:
 type: string
 secret: true
 openrouterApiKey:
 type: string
 secret: true
 tailscaleAuthKey:
 type: string
 secret: true
 tailnetDnsName:
 type: string
 renderApiKey:
 type: string
 secret: true
 renderOwnerId:
 type: string

variables:
 registryAuth:
 - address: ghcr.io
 username: ${ghcrUser}
 password: ${ghcrToken}
 # Open WebUI reaches Hermes at its private slug; you reach Open WebUI on the tailnet.
 hermesApiBaseUrl: http://${hermes-agent.slug}:8642/v1
 webuiTailnetUrl: https://open-webui.${tailnetDnsName}

resources:
 # Render provider auth (from config or ESC).
 render:
 type: pulumi:providers:render
 properties:
 apiKey: ${renderApiKey}
 ownerId: ${renderOwnerId}

 # Secrets generated in state: the replacement for `openssl rand -base64 32`.
 hermes-shared-key:
 type: random:RandomBytes
 properties:
 length: 32
 webui-secret-key:
 type: random:RandomBytes
 properties:
 length: 32

 # Build + push both images during `pulumi up` (no docker CLI).
 hermes-image:
 type: docker-build:Image
 properties:
 context:
 location: ./hermes
 dockerfile:
 location: ./hermes/Dockerfile
 platforms: [linux/amd64]
 tags:
 - ghcr.io/${ghcrUser}/hermes-agent:latest
 push: true
 registries: ${registryAuth}
 webui-image:
 type: docker-build:Image
 properties:
 context:
 location: ./openwebui
 dockerfile:
 location: ./openwebui/Dockerfile
 platforms: [linux/amd64]
 tags:
 - ghcr.io/${ghcrUser}/open-webui:latest
 push: true
 registries: ${registryAuth}

 # Credential Render uses to pull the private GHCR images.
 ghcr:
 type: render:RegistryCredential
 properties:
 name: ghcr
 registry: GITHUB
 username: ${ghcrUser}
 authToken: ${ghcrToken}
 options:
 provider: ${render}

 # Hermes: a PRIVATE Render service. No public URL; encrypted env vars are the secret mechanism.
 hermes-agent:
 type: render:PrivateService
 properties:
 name: hermes-agent
 plan: standard  # 2 GB; the gateway OOMs on starter's 512 MB
 region: ${renderRegion}
 runtimeSource:
 image:
 imageUrl: ghcr.io/${ghcrUser}/hermes-agent
 digest: ${hermes-image.digest}
 registryCredentialId: ${ghcr.id}
 disk:
 name: hermes-data
 mountPath: /opt/data
 sizeGb: 5
 envVars:
 PORT: { value: "8642" }
 API_SERVER_ENABLED: { value: "true" }
 API_SERVER_HOST: { value: "0.0.0.0" }
 API_SERVER_PORT: { value: "8642" }
 API_SERVER_MODEL_NAME: { value: "${modelDefault}" }
 HERMES_ACCEPT_HOOKS: { value: "1" }
 API_SERVER_KEY: { value: "${hermes-shared-key.base64}" }
 OPENROUTER_API_KEY: { value: "${openrouterApiKey}" }
 MODAL_TOKEN_ID: { value: "${modalTokenId}" }
 MODAL_TOKEN_SECRET: { value: "${modalTokenSecret}" }
 options:
 provider: ${render}

 # Open WebUI: also a PRIVATE Render service, joined to your tailnet by its image.
 open-webui:
 type: render:PrivateService
 properties:
 name: open-webui
 plan: standard  # 2 GB; Open WebUI OOMs on starter's 512 MB
 region: ${renderRegion}  # must match Hermes for private networking
 runtimeSource:
 image:
 imageUrl: ghcr.io/${ghcrUser}/open-webui
 digest: ${webui-image.digest}
 registryCredentialId: ${ghcr.id}
 disk:
 name: openwebui-data
 mountPath: /app/backend/data
 sizeGb: 5
 envVars:
 PORT: { value: "8080" }
 OPENAI_API_BASE_URL: { value: "${hermesApiBaseUrl}" }
 ENABLE_OPENAI_API: { value: "true" }
 ENABLE_OLLAMA_API: { value: "false" }
 DEFAULT_MODELS: { value: "${modelDefault}" }
 WEBUI_AUTH: { value: "true" }
 WEBUI_URL: { value: "${webuiTailnetUrl}" }
 ENABLE_LOGIN_FORM: { value: "true" }
 ENABLE_SIGNUP: { value: "true" }
 DEFAULT_USER_ROLE: { value: "admin" }
 ENABLE_PERSISTENT_CONFIG: { value: "false" }
 RAG_EMBEDDING_ENGINE: { value: "openai" }
 BYPASS_EMBEDDING_AND_RETRIEVAL: { value: "true" }
 OFFLINE_MODE: { value: "true" }
 HF_HUB_OFFLINE: { value: "1" }
 OPENAI_API_KEY: { value: "${hermes-shared-key.base64}" }
 WEBUI_SECRET_KEY: { value: "${webui-secret-key.base64}" }
 TS_AUTHKEY: { value: "${tailscaleAuthKey}" }
 TS_HOSTNAME: { value: "open-webui" }
 options:
 provider: ${render}
 dependsOn:
 - ${hermes-agent}

outputs:
 hermesInternalUrl: ${hermesApiBaseUrl}
 # Open this from any device on your tailnet:
 openWebUiTailnetUrl: ${webuiTailnetUrl}

Neither box is published to the internet. The same code, plus the Dockerfiles and the Tailscale entrypoint, is in the companion repo:

github.com/dirien/hermes-agent-pulumi

Cost

Two details shape the bill. The host starts on Render’s free Hobby workspace, but a private service with a persistent disk runs on paid compute, so you need a card on file the moment you add them. There is no free-tier version of this architecture. Both services also need the 2 GB Standard plan, since the gateway and Open WebUI each OOM on the 512 MB Starter.

	Hermes gateway	Open WebUI
Plan	Standard (2 GB)	Standard (2 GB)
Compute	~$25/mo	~$25/mo
Disk	5 GB	5 GB
Public URL	none	none (tailnet only)

That lands the host around $50/month, in line with what a comparable managed setup runs. Modal and OpenRouter bill by usage on top, so the total tracks how hard the agent works rather than a flat number. Tailscale is free for a personal tailnet, so the private gateway adds nothing to that.

The persistent disk pins each service to a single instance, so there is no autoscaling, and a redeploy drops a few seconds of connectivity while the old instance lets go of the disk. For a single-user agent that is a fine trade, and it is why “stand it up in a second region” is a copy-the-config move and not a live failover.

The OpenRouter Activity dashboard: 56 requests and 738K tokens of gpt-5.5 usage, all routed through one key.

Running the deployment

With your ESC environment referenced in Pulumi.dev.yaml, deploy with:

pulumi up

This generates the Render SDK’s resources, builds and pushes both images through buildx, and creates the two private services with their disks and encrypted env vars, all in one run, with no docker CLI and no secret import hiding in a script. When it finishes, both services show up in the Render dashboard with no public URL.

The hermes-agent and open-webui private services in the Render dashboard, both deployed with no public URL.

Access the agent

Give it a few minutes after pulumi up finishes. The images still have to be pulled and the containers booted, and Open WebUI has to join your tailnet before the URL resolves. Refresh until it loads.

Open WebUI is reachable only from a device on your tailnet, at https://open-webui.<your-tailnet>.ts.net, with no domain to buy, no DNS to point, and no certificate to manage. Open it, sign up so the first account becomes the admin, and ask the agent to run a Python command. It should fire up a Modal sandbox and return the result, with nothing exposed to the public internet at any point.

Open WebUI on the tailnet URL: the gpt-5.5 agent runs sum(i*i for i in range(1, 1001)) in a Modal sandbox and returns 333833500.

When the agent runs that code, Modal builds a throwaway sandbox specifically for it. There is no Modal resource to declare, no Modal CLI to call, and no Modal provider to bridge. The Hermes service carries MODAL_TOKEN_ID and MODAL_TOKEN_SECRET as two encrypted env vars, and that is the whole footprint.

The Modal dashboard: the per-task sandboxes the Hermes agent spun up at runtime to execute code.

Verify the deployment (optional)

If the chat UI does not load, give the services a few minutes to finish their first boot, then check two things:

Render dashboard logs for the hermes-agent and open-webui services, to confirm both started and pulled their images.
Tailscale admin console (Machines), to confirm the open-webui node joined your tailnet. If it did not, the TS_AUTHKEY is likely expired or not reusable.

Keep your AI agent private

Deploy your Hermes agent across Render, Modal, and Tailscale as one Pulumi program, with secrets held in Pulumi ESC and nothing exposed to the public internet.

Get started

Security considerations

Self-hosted AI servers get found fast: scanners like Shodan and Censys enumerate a freshly exposed one within hours to days, and the code-capable ones are already under active attack. Running an always-on agent on a machine you also use for everything else invites prompt injection on top of that. The answer here is to keep the agent unroutable from the internet and to isolate the code it runs. That defeats the scanner: nobody finds an open port to attack. It does less against the agent being turned against you from the inside, which is the harder problem.

One detail makes that isolation essential. In a headless container there is no one at the terminal to approve anything, and the same is true of its cron and CI runs, so the deployment runs Hermes with HERMES_ACCEPT_HOOKS=1 to auto-accept the shell hooks it would otherwise pause on. The practical result is that the agent’s code runs with no human in the loop, which is exactly why the Modal sandbox has to carry the weight: when the model writes a bad command, the throwaway container it runs in is what stands between that command and the gateway’s credentials, not a confirmation prompt.

Concern	Typical self-host	This deployment
Gateway reachability	Public port, or behind a login	Private service, no public URL
Chat UI reachability	Public hostname + auth	Tailnet only (`tailscale serve`)
Code execution	Runs next to the gateway	Isolated Modal sandbox, torn down after
Command approval	Human approves dangerous commands	Headless: isolation replaces the prompt
Secrets in transit	Exposed if accessed over HTTP	Encrypted env vars; tailnet-encrypted access

This is private, which is not the same as fully trusted. A few places the boundary still leaks:

The shared bearer never rotates. Hermes is unroutable from the internet, but it is wide open to Open WebUI, and the two share one static bearer key. Whoever owns the front end owns the gateway behind it. Rotate it periodically.
The tailnet policy is click-ops. The ACLs, the node’s tags, and the one-time HTTPS toggle live in the Tailscale admin console, not in pulumi up, and the reusable key has no tag scoping its blast radius. The Tailscale provider can manage that policy declaratively if you want it in code.
Signup defaults to admin. Fine on a single-user tailnet, the first thing to lock down (ENABLE_SIGNUP, DEFAULT_USER_ROLE) once more than one person can reach the URL.
Every messaging client is another entry point. Each platform you wire up adds another way in, which is why the tailnet is the baseline for securing this, not the full extent of it.
A compromised agent can still reach out. The private core stops external discovery, but it does not contain the agent itself. The gateway holds the Modal and OpenRouter tokens as env vars and can call out freely, so a prompt-injected agent could read its own environment and send them somewhere; the Modal sandbox isolates the code the agent runs, not the credentials it holds. Cap and rotate the OpenRouter key, keep the Modal token off the gateway, and allowlist outbound traffic, which on Render means a forward-proxy sidecar (Render gives you dedicated outbound IPs and inbound rules, but no destination egress filter).

My recommendations:

Keep both services private; never give Hermes a public URL
Run code in Modal sandboxes, since HERMES_ACCEPT_HOOKS=1 means no human approves commands
Rotate the shared bearer key and the Tailscale auth key periodically
Cap and rotate the OpenRouter key; a leaked credential is the likelier failure mode than an open port
Use Pulumi ESC for secrets instead of hardcoding
Lock down Open WebUI signup once more than one person can reach it
Manage Tailscale ACLs and tags deliberately, in the admin console or with the Tailscale provider

What’s next?

The deployment is the foundation the agent builds on. A private agent becomes useful when it remembers earlier context, runs code without a human at the terminal, and initiates contact on its own. The disk is what makes this persist: its memory and its schedule live on that disk, so they survive every restart.

It schedules itself. Hermes ships a first-class cron you drive in plain language, either by asking the agent in the chat window or through its CLI. The schedule takes intervals, five-field cron, or one-shots:

hermes cron create "every 1h" \
 "Scrape <listing-url> for the price, compare it with seen.json in the sandbox, message me on Telegram only if it dropped, and otherwise reply exactly [SILENT]." \
 --deliver telegram

The [SILENT] reply suppresses delivery when nothing changed, so the watcher only speaks up when there is something to say. Scheduled runs skip memory by default, so polling does not pollute what the agent has learned.

It connects where you work, with the same secret pattern. Messaging clients attach to the same gateway, and their tokens ride as encrypted env vars on the Hermes service, the exact shape you used for the Modal pair:

// alongside MODAL_TOKEN_ID on the hermes service:
TELEGRAM_BOT_TOKEN: { value: cfg.requireSecret("telegramBotToken") },

plus a platform block you add to config.yaml (the image ships only the model and terminal blocks; Hermes supports the messaging platforms on top, per its docs):

gateway:
 platforms:
 telegram:
 require_mention: true

With those two pieces, a few things are genuinely doable today:

A price or uptime watcher that only speaks up when something changed, using the [SILENT] and persistent-sandbox dedup pattern above.
A daily briefing that ranks and dedups your feeds and delivers the top items each morning, the documented daily-briefing bot. If you want it to adapt to your taste over time, that is the optional Honcho memory provider’s job; it reads your preferences out of the conversation itself. The built-in file memory has no version of that.
A PR-review teammate that reviews open pull requests against your repo’s AGENTS.md conventions and saves recurring patterns as a skill, so the fifth review needs less hand-holding than the first.

A few limits are worth stating plainly, since demos tend to overstate the capabilities. Hermes does not ship Gmail, Calendar, or market integrations out of the box; those are wired up as MCP servers or skills, which is more work than a launch video implies. It curates its own memory and improves its own skills, but it does not retrain the underlying model or autonomously change its high-level strategy, so “self-learning” here means whatever it writes into memory and skills each run.

Conclusion

Deploying a Hermes agent with infrastructure as code means you can reproduce the setup anytime, version control it, and tear it down with a single pulumi destroy. Keeping both services private, with no public URL and no exposed ports, means the code-executing core never sits on the internet for someone to find.

The part worth carrying to the next service you deploy: not every layer has a provider, and that is fine. The task is to tell a real resource apart from a runtime dependency wearing a costume. Render and the images are resources you declare; Modal and Tailscale are credentials you hand over. Draw that map first, and the program follows from it.

To generate that map instead of writing it by hand, Pulumi Neo can take a target architecture like this one and produce a first draft of the program. The agent side of this shift is covered in How Building AI Agents Has Changed in 2026 and the platform side in Agent Sprawl Is Here. Your IaC Platform Is the Answer..

If you run into issues or have questions, drop by the Pulumi Community Slack or GitHub Discussions. New to Pulumi? Get started here.

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.

Deploy OpenClaw on AWS or Hetzner Securely with Pulumi and Tailscale

Engin Diri — Mon, 26 Jan 2026 00:00:00 +0000

Update (January 2026): The lobster has molted into its final form! From Clawdbot to Moltbot to OpenClaw. With 100k+ GitHub stars and 2M visitors in a week, the project finally has a name that’ll stick. The CLI command is now openclaw and the new handle is @openclaw. Same mission: AI that actually does things. Your assistant. Your machine. Your rules. See the official getting started guide for updated installation instructions.

Update (April 2026): Refreshed for OpenClaw 2026.4.27. Upstream now recommends Node 24, but the cloud-init script in this post still installs Node 22 — both work. If you’d like Node 24, change the nvm install 22 lines to nvm install 24.

The short version: Deploy OpenClaw to AWS or Hetzner with a Pulumi TypeScript program that provisions the VM, installs Docker, Node, and OpenClaw, then joins the instance to your Tailscale network so the gateway and browser ports stay private. One pulumi up to deploy, one pulumi destroy to tear down. Total cost: about $33/month on AWS or $7/month on Hetzner.

OpenClaw is everywhere right now. The open-source AI assistant gained 9,000 GitHub stars in a single day, received public praise from former Tesla AI head Andrej Karpathy, and has sparked a global run on Mac Minis as developers scramble to give this “lobster assistant” a home. Users are calling it “Jarvis living in a hard drive” and “Claude with hands”—the personal AI assistant that Siri promised but never delivered.

The Mac Mini craze is real: people are buying dedicated hardware just to run OpenClaw, with some enthusiasts purchasing 40 Mac Minis at once. Even Logan Kilpatrick from Google DeepMind couldn’t resist ordering one. But here’s the thing: you don’t actually need a Mac Mini. OpenClaw runs anywhere: on a VPS, in the cloud, or on that old laptop gathering dust.

With all this hype, I had to try it myself. But instead of clicking through the AWS console or running manual commands on a VPS, I wanted to do it right from the start: infrastructure as code with Pulumi. Why? Because when I inevitably want to tear it down, spin up a new instance, or deploy to a different region, I don’t want to remember which buttons I clicked three weeks ago. I want a single pulumi up command.

Dan got the assignment right:

In this post, I’ll show you how to deploy OpenClaw to AWS or Hetzner Cloud (if you want European data residency or just want to spend less). We’ll use Pulumi to define the infrastructure and Tailscale to keep your AI assistant off the public internet.

What is OpenClaw?

OpenClaw is an open-source AI assistant created by Peter Steinberger that runs on your own infrastructure. It connects to WhatsApp, Slack, Discord, Google Chat, Signal, and iMessage. It can control browsers, generate videos and images, clone your voice for voice notes, and run scheduled tasks via cron. There’s a skills system for extending functionality, and you can run it on pretty much anything: Mac Mini, Raspberry Pi, VPS, laptop, or gaming PC.

The difference from cloud-hosted AI? OpenClaw runs on your server, not Anthropic’s. It’s available 24/7 across all your devices, can schedule automated tasks, and keeps your entire conversation history locally. Check the official OpenClaw documentation for the full feature list.

Prerequisites

Before getting started, ensure you have:

Pulumi CLI installed and configured
A Pulumi Cloud account
AWS account (for AWS deployment)
Hetzner Cloud account (for European deployment)
Anthropic API key
Node.js 22+ installed (Node 24 recommended; the cloud-init script in this post installs Node 22 inside the VM)
Tailscale account with HTTPS enabled (one-time setup in admin console)

This guide uses Anthropic’s API, but OpenClaw works with other providers too. Check the providers documentation if you’d rather use OpenAI, Google Gemini, or a local model via Ollama.

Understanding OpenClaw architecture

OpenClaw uses a gateway-centric architecture where a single daemon acts as the control plane for all messaging, tool execution, and client connections:

Component	Port	Description
Gateway	18789	WebSocket server handling channels, nodes, sessions, and hooks
Browser control	18791	Headless Chrome instance for web automation
Docker sandbox	-	Isolated container environment for running tools safely

The Gateway connects to messaging platforms (WhatsApp, Slack, Discord, etc.), the CLI, the web UI, and mobile apps. The Browser component lets OpenClaw open web pages, fill forms, scrape data, and download files. Docker sandboxing runs bash commands in isolated containers so your bot can execute code without risking your host system.

Setting up ESC for secrets management

Deploying OpenClaw means handling sensitive credentials: API keys, auth tokens, cloud provider secrets. You don’t want these hardcoded or scattered across environment variables. Pulumi ESC (Environments, Secrets, and Configuration) stores them securely and passes them directly to your Pulumi program — the same pattern Pulumi uses to eliminate long-lived CI secrets across 70+ repos.

Create a new ESC environment:

pulumi env init <your-org>/openclaw-secrets

Add your secrets to the environment:

values:
 anthropicApiKey:
 fn::secret: "sk-ant-xxxxx"
 tailscaleAuthKey:
 fn::secret: "tskey-auth-xxxxx"
 tailnetDnsName: "tailxxxxx.ts.net"
 hcloudToken:
 fn::secret: "your-hetzner-api-token"
 pulumiConfig:
 anthropicApiKey: ${anthropicApiKey}
 tailscaleAuthKey: ${tailscaleAuthKey}
 tailnetDnsName: ${tailnetDnsName}
 hcloud:token: ${hcloudToken}

Then create a Pulumi.dev.yaml file in your project to reference the environment:

environment:
 - <your-org>/openclaw-secrets

This approach keeps your secrets out of your codebase and passes them directly to OpenClaw during automated onboarding. To prevent stack-level overrides of these values, see locking down ESC values with fn::final.

Securing with Tailscale

By default, deploying OpenClaw exposes SSH (port 22), the gateway (port 18789), and browser control (port 18791) to the public internet. This is convenient for testing but not ideal for production use.

Tailscale creates a secure mesh VPN that lets you access your OpenClaw instance without exposing unnecessary ports publicly. When you provide a Tailscale auth key, the Pulumi program:

Removes gateway and browser ports from public access
Keeps SSH as fallback for debugging if Tailscale setup fails
Installs Tailscale on the instance during provisioning (after other dependencies)
Enables Tailscale SSH so you can SSH via Tailscale without managing keys
Joins your tailnet automatically using the auth key

The Pulumi program installs Docker, Node.js, and OpenClaw first, then configures Tailscale last. This ensures that even if the Tailscale auth key is invalid or expired, you can still SSH in via the public IP to troubleshoot.

To generate a Tailscale auth key:

Go to Tailscale Admin Console
Click “Generate auth key”
Enable “Reusable” if you plan to redeploy
Copy the key and add it to your ESC environment

Deploying to AWS

Let’s walk through the complete AWS deployment. Create a new Pulumi project:

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

Install the required dependencies:

npm install @pulumi/aws @pulumi/tls

Do not use t3.micro instances for OpenClaw. The 1 GB memory is insufficient for installation. Use t3.medium (4 GB) or t3.large (8 GB) instead.

The Pulumi program

Running OpenClaw on AWS means setting up a VPC, subnets, security groups, an EC2 instance, SSH keys, and a cloud-init script that installs everything. That’s a lot of clicking in the AWS console. The Pulumi program below defines all of it in code.

Replace the contents of index.ts with the following:

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

const config = new pulumi.Config();

const instanceType = config.get("instanceType") ?? "t3.medium";
const anthropicApiKey = config.requireSecret("anthropicApiKey");
const model = config.get("model") ?? "anthropic/claude-sonnet-4";
const enableSandbox = config.getBoolean("enableSandbox") ?? true;
const gatewayPort = config.getNumber("gatewayPort") ?? 18789;
const browserPort = config.getNumber("browserPort") ?? 18791;

const tailscaleAuthKey = config.requireSecret("tailscaleAuthKey");
const tailnetDnsName = config.require("tailnetDnsName");

// Generate a random token for gateway authentication
const gatewayToken = new tls.PrivateKey("openclaw-gateway-token", {
 algorithm: "ED25519",
}).publicKeyOpenssh.apply(key => {
 // Create a deterministic token from the public key (take first 48 hex chars)
 const hash = require("crypto").createHash("sha256").update(key).digest("hex");
 return hash.substring(0, 48);
});

const sshKey = new tls.PrivateKey("openclaw-ssh-key", {
 algorithm: "ED25519",
});

const vpc = new aws.ec2.Vpc("openclaw-vpc", {
 cidrBlock: "10.0.0.0/16",
 enableDnsHostnames: true,
 enableDnsSupport: true,
 tags: { Name: "openclaw-vpc" },
});

const gateway = new aws.ec2.InternetGateway("openclaw-igw", {
 vpcId: vpc.id,
 tags: { Name: "openclaw-igw" },
});

const subnet = new aws.ec2.Subnet("openclaw-subnet", {
 vpcId: vpc.id,
 cidrBlock: "10.0.1.0/24",
 mapPublicIpOnLaunch: true,
 tags: { Name: "openclaw-subnet" },
});

const routeTable = new aws.ec2.RouteTable("openclaw-rt", {
 vpcId: vpc.id,
 routes: [
 {
 cidrBlock: "0.0.0.0/0",
 gatewayId: gateway.id,
 },
 ],
 tags: { Name: "openclaw-rt" },
});

new aws.ec2.RouteTableAssociation("openclaw-rta", {
 subnetId: subnet.id,
 routeTableId: routeTable.id,
});

const securityGroup = new aws.ec2.SecurityGroup("openclaw-sg", {
 vpcId: vpc.id,
 description: "Security group for OpenClaw instance",
 ingress: [
 {
 description: "SSH access (fallback)",
 fromPort: 22,
 toPort: 22,
 protocol: "tcp",
 cidrBlocks: ["0.0.0.0/0"],
 },
 ],
 egress: [
 {
 fromPort: 0,
 toPort: 0,
 protocol: "-1",
 cidrBlocks: ["0.0.0.0/0"],
 },
 ],
 tags: { Name: "openclaw-sg" },
});

const keyPair = new aws.ec2.KeyPair("openclaw-keypair", {
 publicKey: sshKey.publicKeyOpenssh,
});

const ami = aws.ec2.getAmiOutput({
 owners: ["099720109477"],
 mostRecent: true,
 filters: [
 { name: "name", values: ["ubuntu/images/hvm-ssd-gp3/ubuntu-noble-24.04-amd64-server-*"] },
 { name: "virtualization-type", values: ["hvm"] },
 ],
});

const userData = pulumi
 .all([tailscaleAuthKey, anthropicApiKey, gatewayToken])
 .apply(([tsAuthKey, apiKey, gwToken]) => {
 return `#!/bin/bash
set -e

export DEBIAN_FRONTEND=noninteractive

# System updates
apt-get update
apt-get upgrade -y

# Install Docker
curl -fsSL https://get.docker.com | sh
systemctl enable docker
systemctl start docker
usermod -aG docker ubuntu

# Install NVM and Node.js for ubuntu user
sudo -u ubuntu bash << 'UBUNTU_SCRIPT'
set -e
cd ~

# Install NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# Load NVM
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

# Install Node.js 22
nvm install 22
nvm use 22
nvm alias default 22

# Install OpenClaw
npm install -g openclaw@latest

# Add NVM to bashrc if not already there
if ! grep -q 'NVM_DIR' ~/.bashrc; then
 echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.bashrc
 echo '[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"' >> ~/.bashrc
fi
UBUNTU_SCRIPT

# Set environment variables for ubuntu user
echo 'export ANTHROPIC_API_KEY="${apiKey}"' >> /home/ubuntu/.bashrc

# Install and configure Tailscale
echo "Installing Tailscale..."
curl -fsSL https://tailscale.com/install.sh | sh
tailscale up --authkey="${tsAuthKey}" --ssh || echo "WARNING: Tailscale setup failed. Run 'sudo tailscale up' manually."

# Enable systemd linger for ubuntu user (required for user services to run at boot)
loginctl enable-linger ubuntu

# Start user's systemd instance (required for user services during cloud-init)
systemctl start user@1000.service

# Run OpenClaw onboarding as ubuntu user (skip daemon install, do it separately)
echo "Running OpenClaw onboarding..."
sudo -H -u ubuntu ANTHROPIC_API_KEY="${apiKey}" GATEWAY_PORT="${gatewayPort}" bash -c '
export HOME=/home/ubuntu
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

openclaw onboard --non-interactive --accept-risk \
 --mode local \
 --auth-choice apiKey \
 --gateway-port $GATEWAY_PORT \
 --gateway-bind loopback \
 --skip-daemon \
 --skip-skills || echo "WARNING: OpenClaw onboarding failed. Run openclaw onboard manually."
'

# Install daemon service with XDG_RUNTIME_DIR set
echo "Installing OpenClaw daemon..."
sudo -H -u ubuntu XDG_RUNTIME_DIR=/run/user/1000 bash -c '
export HOME=/home/ubuntu
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

openclaw daemon install || echo "WARNING: Daemon install failed. Run openclaw daemon install manually."
'

# Configure gateway for Tailscale Serve (trustedProxies + skip device pairing + set token)
echo "Configuring gateway for Tailscale Serve..."
sudo -H -u ubuntu GATEWAY_TOKEN="${gwToken}" python3 << 'PYTHON_SCRIPT'
import json
import os
config_path = "/home/ubuntu/.openclaw/openclaw.json"
with open(config_path) as f:
 config = json.load(f)
config["gateway"]["trustedProxies"] = ["127.0.0.1"]
config["gateway"]["controlUi"] = {
 "enabled": True,
 "allowInsecureAuth": True
}
config["gateway"]["auth"] = {
 "mode": "token",
 "token": os.environ["GATEWAY_TOKEN"]
}
with open(config_path, "w") as f:
 json.dump(config, f, indent=2)
print("Configured gateway with trustedProxies, controlUi, and token")
PYTHON_SCRIPT

# Enable Tailscale HTTPS proxy (requires HTTPS to be enabled in Tailscale admin console)
echo "Enabling Tailscale HTTPS proxy..."
tailscale serve --bg ${gatewayPort} || echo "WARNING: tailscale serve failed. Enable HTTPS in your Tailscale admin console first."

echo "OpenClaw setup complete!"
`;
 });

const instance = new aws.ec2.Instance("openclaw-instance", {
 ami: ami.id,
 instanceType: instanceType,
 subnetId: subnet.id,
 vpcSecurityGroupIds: [securityGroup.id],
 keyName: keyPair.keyName,
 userData: userData,
 userDataReplaceOnChange: true,
 rootBlockDevice: {
 volumeSize: 30,
 volumeType: "gp3",
 },
 tags: { Name: "openclaw" },
});

export const publicIp = instance.publicIp;
export const publicDns = instance.publicDns;
export const privateKey = sshKey.privateKeyOpenssh;

// Construct the Tailscale MagicDNS hostname from the private IP
// AWS private IPs like 10.0.1.15 become hostnames like ip-10-0-1-15
const tailscaleHostname = instance.privateIp.apply(ip =>
 `ip-${ip.replace(/\./g, "-")}`
);

export const tailscaleUrlWithToken = pulumi.interpolate`https://${tailscaleHostname}.${tailnetDnsName}/?token=${gatewayToken}`;
export const gatewayTokenOutput = gatewayToken;

Deploying to Hetzner

Hetzner Cloud is a solid choice if you need European data residency or want to spend less money. Spoiler: it’s a lot less money.

Hetzner has similar concepts to AWS but different names. EC2 instances become Servers. Security groups become Firewalls. Same idea, different provider. The resource types come from @pulumi/hcloud.

Create a new project for Hetzner:

mkdir openclaw-hetzner && cd openclaw-hetzner
pulumi new typescript

Install the Hetzner provider:

npm install @pulumi/hcloud @pulumi/tls

The default server type cax21 is an ARM-based (Ampere) instance with 4 vCPUs and 8 GB RAM. ARM instances cost less for the same compute. If you need x86 architecture, use ccx13 or similar CCX series instead.

The Hetzner Pulumi program

Replace index.ts with the following:

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

const config = new pulumi.Config();

const serverType = config.get("serverType") ?? "cax21";
const location = config.get("location") ?? "fsn1";
const anthropicApiKey = config.requireSecret("anthropicApiKey");
const model = config.get("model") ?? "anthropic/claude-sonnet-4";
const enableSandbox = config.getBoolean("enableSandbox") ?? true;
const gatewayPort = config.getNumber("gatewayPort") ?? 18789;
const browserPort = config.getNumber("browserPort") ?? 18791;

const tailscaleAuthKey = config.requireSecret("tailscaleAuthKey");
const tailnetDnsName = config.require("tailnetDnsName");

// Generate a random token for gateway authentication
const gatewayToken = new tls.PrivateKey("openclaw-gateway-token", {
 algorithm: "ED25519",
}).publicKeyOpenssh.apply(key => {
 const hash = require("crypto").createHash("sha256").update(key).digest("hex");
 return hash.substring(0, 48);
});

const sshKey = new tls.PrivateKey("openclaw-ssh-key", {
 algorithm: "ED25519",
});

const hcloudSshKey = new hcloud.SshKey("openclaw-sshkey", {
 publicKey: sshKey.publicKeyOpenssh,
});

const firewallRules: hcloud.types.input.FirewallRule[] = [
 {
 direction: "out",
 protocol: "tcp",
 port: "any",
 destinationIps: ["0.0.0.0/0", "::/0"],
 description: "Allow all outbound TCP",
 },
 {
 direction: "out",
 protocol: "udp",
 port: "any",
 destinationIps: ["0.0.0.0/0", "::/0"],
 description: "Allow all outbound UDP",
 },
 {
 direction: "out",
 protocol: "icmp",
 destinationIps: ["0.0.0.0/0", "::/0"],
 description: "Allow all outbound ICMP",
 },
 {
 direction: "in",
 protocol: "tcp",
 port: "22",
 sourceIps: ["0.0.0.0/0", "::/0"],
 description: "SSH access (fallback)",
 },
];

const firewall = new hcloud.Firewall("openclaw-firewall", {
 rules: firewallRules,
});

const userData = pulumi
 .all([tailscaleAuthKey, anthropicApiKey, gatewayToken])
 .apply(([tsAuthKey, apiKey, gwToken]) => {
 return `#!/bin/bash
set -e

export DEBIAN_FRONTEND=noninteractive

# System updates
apt-get update
apt-get upgrade -y

# Install Docker
curl -fsSL https://get.docker.com | sh
systemctl enable docker
systemctl start docker

# Create ubuntu user (Hetzner uses root by default)
useradd -m -s /bin/bash -G docker ubuntu || true

# Install NVM and Node.js for ubuntu user
sudo -u ubuntu bash << 'UBUNTU_SCRIPT'
set -e
cd ~

# Install NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# Load NVM
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

# Install Node.js 22
nvm install 22
nvm use 22
nvm alias default 22

# Install OpenClaw
npm install -g openclaw@latest

# Add NVM to bashrc if not already there
if ! grep -q 'NVM_DIR' ~/.bashrc; then
 echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.bashrc
 echo '[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"' >> ~/.bashrc
fi
UBUNTU_SCRIPT

# Set environment variables for ubuntu user
echo 'export ANTHROPIC_API_KEY="${apiKey}"' >> /home/ubuntu/.bashrc

# Install and configure Tailscale
echo "Installing Tailscale..."
curl -fsSL https://tailscale.com/install.sh | sh
tailscale up --authkey="${tsAuthKey}" --ssh || echo "WARNING: Tailscale setup failed. Run 'sudo tailscale up' manually."

# Enable systemd linger for ubuntu user (required for user services to run at boot)
loginctl enable-linger ubuntu

# Start user's systemd instance (required for user services during cloud-init)
systemctl start user@1000.service

# Run OpenClaw onboarding as ubuntu user (skip daemon install, do it separately)
echo "Running OpenClaw onboarding..."
sudo -H -u ubuntu ANTHROPIC_API_KEY="${apiKey}" GATEWAY_PORT="${gatewayPort}" bash -c '
export HOME=/home/ubuntu
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

openclaw onboard --non-interactive --accept-risk \
 --mode local \
 --auth-choice apiKey \
 --gateway-port $GATEWAY_PORT \
 --gateway-bind loopback \
 --skip-daemon \
 --skip-skills || echo "WARNING: OpenClaw onboarding failed. Run openclaw onboard manually."
'

# Install daemon service with XDG_RUNTIME_DIR set
echo "Installing OpenClaw daemon..."
sudo -H -u ubuntu XDG_RUNTIME_DIR=/run/user/1000 bash -c '
export HOME=/home/ubuntu
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

openclaw daemon install || echo "WARNING: Daemon install failed. Run openclaw daemon install manually."
'

# Configure gateway for Tailscale Serve (trustedProxies + skip device pairing + set token)
echo "Configuring gateway for Tailscale Serve..."
sudo -H -u ubuntu GATEWAY_TOKEN="${gwToken}" python3 << 'PYTHON_SCRIPT'
import json
import os
config_path = "/home/ubuntu/.openclaw/openclaw.json"
with open(config_path) as f:
 config = json.load(f)
config["gateway"]["trustedProxies"] = ["127.0.0.1"]
config["gateway"]["controlUi"] = {
 "enabled": True,
 "allowInsecureAuth": True
}
config["gateway"]["auth"] = {
 "mode": "token",
 "token": os.environ["GATEWAY_TOKEN"]
}
with open(config_path, "w") as f:
 json.dump(config, f, indent=2)
print("Configured gateway with trustedProxies, controlUi, and token")
PYTHON_SCRIPT

# Enable Tailscale HTTPS proxy (requires HTTPS to be enabled in Tailscale admin console)
echo "Enabling Tailscale HTTPS proxy..."
tailscale serve --bg ${gatewayPort} || echo "WARNING: tailscale serve failed. Enable HTTPS in your Tailscale admin console first."

echo "OpenClaw setup complete!"
`;
 });

const server = new hcloud.Server("openclaw-server", {
 serverType: serverType,
 location: location,
 image: "ubuntu-24.04",
 sshKeys: [hcloudSshKey.id],
 firewallIds: [firewall.id.apply(id => Number(id))],
 userData: userData,
 labels: {
 purpose: "openclaw",
 },
});

export const ipv4Address = server.ipv4Address;
export const privateKey = sshKey.privateKeyOpenssh;

// Construct the Tailscale MagicDNS hostname from the server name
// Hetzner servers use their name as the hostname
const tailscaleHostname = server.name;

export const tailscaleUrlWithToken = pulumi.interpolate`https://${tailscaleHostname}.${tailnetDnsName}/?token=${gatewayToken}`;
export const gatewayTokenOutput = gatewayToken;

You can find both programs in the Pulumi examples repo under openclaw/:

github.com/pulumi/examples

Cost comparison

Before deploying, let’s compare the costs between AWS and Hetzner for running OpenClaw 24/7:

	AWS (t3.medium)	Hetzner (cax21)
vCPUs	2	4
Memory	4 GB	8 GB
Storage	30 GB gp3 (+$2.40/mo)	80 GB NVMe (included)
Traffic	Pay per GB	20 TB included
Architecture	x86 (Intel/AMD)	ARM (Ampere)
Hourly price	$0.0416	€0.0104 (~$0.011)
Monthly price	~$33 (with storage)	€6.49 (~$7)
Annual cost	~$396	~$84

Hetzner gives you double the vCPUs, double the RAM, at less than a quarter of the price. The trade-off? ARM architecture instead of x86. But OpenClaw doesn’t care - it’s just Node.js and Docker.

Prices are for on-demand instances as of January 2026. AWS prices are for us-east-1; Hetzner prices exclude VAT. Both include standard networking and storage. Check AWS EC2 pricing and Hetzner Cloud pricing for current rates.

Running the deployment

With your ESC environment configured in Pulumi.dev.yaml, deploy with:

pulumi up

After deployment completes, you’ll see outputs similar to:

Outputs:
 gatewayTokenOutput : "786c099cc8f8bf20dbebf40b8b51b75cf5cdab25..."
 privateKey : [secret]
 publicDns : "ec2-x-x-x-x.compute-1.amazonaws.com"
 publicIp : "x.x.x.x"
 tailscaleUrlWithToken: "https://ip-10-0-1-x.tailxxxxx.ts.net/?token=786c099..."

The tailscaleUrlWithToken output provides the complete URL with authentication token. Copy and paste it into your browser to access the OpenClaw web UI.

Output names vary slightly between providers: AWS uses publicIp and publicDns, while Hetzner uses ipv4Address. The Tailscale hostname is derived from the instance’s private IP (AWS) or server name (Hetzner).

Automated onboarding

The Pulumi program runs OpenClaw’s non-interactive onboarding during instance provisioning. It uses your Anthropic API key from ESC, binds the gateway to loopback with Tailscale Serve as the HTTPS proxy, generates a secure gateway token (exported in Pulumi outputs), installs the daemon as a systemd user service, and configures trustedProxies and controlUi.allowInsecureAuth to skip device pairing when accessed via Tailscale.

The cloud-init script runs openclaw onboard --non-interactive with all necessary flags, then configures the gateway for secure Tailscale access. Your instance is ready as soon as provisioning finishes.

Access the web UI

Please wait 3-5 minutes after pulumi up completes. The cloud-init script runs after the instance launches and needs time to install Docker, Node.js, OpenClaw, and Tailscale, then run the onboarding process and start the daemon. Periodically refresh the page until it loads. If the page still doesn’t load after 5 minutes, see Verify the deployment to troubleshoot.

The easiest way to access the OpenClaw web UI is to use the tailscaleUrlWithToken output from Pulumi:

# Get the full URL with token
pulumi stack output tailscaleUrlWithToken

Copy and paste this URL into your browser. The URL includes both the Tailscale MagicDNS hostname and the authentication token, so you can access the web UI directly.

Finding your tailnet DNS name: Go to the Tailscale admin console and look under the DNS section for your tailnet name (e.g., tailxxxxx.ts.net). You can also find your machines and their MagicDNS hostnames in the Machines tab.

Token-based authentication provides an additional layer of security on top of Tailscale’s network-level authentication. Only devices on your tailnet can reach the URL, and the token prevents unauthorized access if someone gains access to your tailnet.

From the web UI, you can connect messaging channels (WhatsApp, Discord, Slack), configure skills and integrations, and manage settings.

Verify the deployment (optional)

If you encounter issues accessing the web UI, you can SSH into your instance to troubleshoot:

# Check your Tailscale admin console for the new machine
ssh ubuntu@<tailscale-ip>

# Check OpenClaw gateway status
systemctl --user status openclaw-gateway

Test your assistant

Open the gateway dashboard using the tailscaleUrlWithToken output and use the built-in chat to test your assistant:

Your personal AI assistant is now running 24/7 on your own infrastructure, accessible securely through Tailscale.

Redeploy OpenClaw with one command

With your infrastructure defined in Pulumi, you can move OpenClaw to a new region, rebuild it, or tear it down with pulumi destroy, without remembering which console buttons you clicked.

Get started

Security considerations

When self-hosting an AI assistant, security matters. OpenClaw’s rapid adoption meant thousands of instances spun up in days, and not everyone locked them down. The community noticed:

The tweet isn’t exaggerating. A quick Shodan search shows exposed gateways on port 18789 with shell access, browser automation, and API keys up for grabs:

Don’t let your instance be one of them.

Concern	Without Tailscale	With Tailscale
SSH access	Public (port 22 open)	Public fallback + Tailscale SSH
Gateway access	Public (port 18789 open)	Private (Tailscale only)
Browser control	Public (port 18791 open)	Private (Tailscale only)
API keys in transit	Exposed if gateway accessed over HTTP	Protected by Tailscale encryption
Attack surface	3 open ports	1 open port (SSH fallback)

SSH remains accessible as a fallback even with Tailscale enabled. This allows you to troubleshoot if Tailscale fails to connect. Once you’ve confirmed Tailscale is working, you can manually remove the SSH ingress rule from your security group for maximum security.

My recommendations:

Always use Tailscale for production
Rotate your auth keys periodically
Use Pulumi ESC for secrets instead of hardcoding
Enable Tailscale SSH to avoid managing keys manually
Monitor your Tailscale admin console for unauthorized devices
Remove the SSH fallback after confirming Tailscale works if you want zero public ports

What’s next?

Now that OpenClaw is running, you can install skills (voice generation, video creation, browser automation), set up scheduled tasks with cron, invite colleagues to your tailnet for shared access, or connect additional channels like WhatsApp and Discord.

For a deeper case study of running an AI assistant on Pulumi-managed infrastructure, see how we built Platybot, or read our KubeCon EU 2026 recap on the year AI moved into production on Kubernetes.

Conclusion

Deploying OpenClaw with infrastructure as code means you can reproduce your setup anytime, version control it, and tear it down with a single command. Adding Tailscale keeps it private - no exposed ports, no hoping you configured your firewall correctly at 2am.

If you run into issues or have questions, drop by the Pulumi Community Slack or GitHub Discussions.

New to Pulumi? Get started here.

How Ralph Wiggum Built a Serverless SaaS with Pulumi

Engin Diri — Wed, 14 Jan 2026 00:00:00 +0000

I was about to do something that felt either genius or completely reckless: hand over my AWS credentials to an AI and step away from my computer. The technique is called “Ralph Wiggum,” named after the Simpsons character who eats glue and says “I’m in danger” while everything burns around him. And honestly, that felt about right for what I was attempting.

The problem with AI coding assistants

If you have spent any time with AI coding assistants, you know the frustration. You are in the middle of a task. It is going great. Claude is writing beautiful infrastructure code, understanding your architecture, making progress… and then it says “I have completed your request.”

You stare at the screen. “No. No, you have not. You maybe did a third of what I asked.”

So you reprompt it. It does a little more. Then it stops again. You are babysitting. The whole point of using an AI assistant was to save time, but if you have to check on it every five minutes, you are not saving anything. You are just a very expensive supervisor.

This is the problem Geoffrey Huntley decided to solve.

What if we just do not let it stop?

Geoffrey Huntley, a developer based in rural Australia (who, according to internet lore, lives on a property with goats), had a deceptively simple idea: what if every time Claude Code finishes and tries to exit, we just feed it the prompt again?

He named the technique “Ralph Wiggum” because the character embodies a kind of childlike persistence. Ralph repeatedly fails, makes silly mistakes, yet stubbornly continues in an endless loop until he eventually succeeds. Sound familiar? That is exactly how AI coding agents work. They make mistakes. They try again. They iterate.

The philosophy behind Ralph is beautifully stated: “Better to fail predictably than succeed unpredictably.” Every failure is just data for the next iteration.

How the Ralph loop works

At its core, the Ralph Wiggum technique is almost embarrassingly simple. It is a bash loop:

while true; do
 cat PROMPT.md | claude --print --dangerously-skip-permissions
done

That is it. That is the whole thing. You write your instructions in a PROMPT.md file, and the loop keeps feeding it to Claude Code over and over.

But here is why it works: each time Claude starts up, it looks at the project. It sees the files that exist, the code that is already written, the git history. It is not starting from zero. It picks up where it left off, sees what still needs to be done, and keeps going.

The official Claude Code plugin formalizes this with some important additions:

Completion promises: You tell Claude to output a specific string like <promise>COMPLETE</promise> when it has genuinely finished
Max iterations: A safety limit so your API bill does not reach infinity
Stop hooks: The mechanism that intercepts exit attempts and re-injects the prompt

To install it:

/plugin install ralph-wiggum@ghuntley

For end-to-end testing of deployed infrastructure, you will also want the Playwright MCP server. This lets Claude interact with your deployed application in a real browser:

claude mcp add playwright npx @playwright/mcp@latest

Why Pulumi is perfect for Ralph

Infrastructure as code has something most application code does not: objective success criteria. Your Lambda either deploys or it does not. Your DynamoDB table either exists or it does not. Tests either pass or they fail.

This makes Pulumi an ideal candidate for autonomous AI development:

Clear completion signals: pulumi preview and pulumi up provide unambiguous feedback
Iterative feedback: Failed deployments tell Claude exactly what went wrong
Testable outputs: You can write integration tests that verify your infrastructure actually works
Registry access: With the Pulumi MCP server, Claude has real-time access to documentation and examples

The experiment

I decided to build a serverless URL shortener on AWS. Not because the world needs another URL shortener, but because it is the perfect test case: multiple AWS services, clear requirements, and objective success criteria. But I did not want just a basic demo. I wanted a full SaaS-like experience with a polished frontend.

Here is the PROMPT.md file I wrote:

# Build a Production-Ready URL Shortener SaaS on AWS

Using Pulumi TypeScript, create a complete URL shortener SaaS with a polished frontend experience.

## Infrastructure Requirements
- DynamoDB table for storing URL mappings (shortCode -> originalUrl, clickCount, createdAt)
- Lambda functions for: creating short URLs, redirecting to original URLs, getting stats
- API Gateway REST API exposing the Lambda functions
- S3 bucket for the React frontend with static website hosting
- CloudFront distribution with HTTPS for the frontend and API
- Use the Pulumi ESC environment pulumi-idp/auth for the AWS credentials

## Frontend Requirements (Use /frontend-design skill)
Create a polished, production-ready SaaS website with:

### Landing Page
- Hero section with catchy headline and URL input form
- Feature highlights (fast redirects, analytics, custom aliases)
- Pricing section (Free tier, Pro tier, Enterprise tier)
- Testimonials section with 3 fake but realistic customer reviews
- Footer with links to Docs, Privacy, Terms

### Dashboard Page
- URL shortening form with optional custom alias
- List of created short URLs with click counts
- Copy-to-clipboard functionality
- Delete URL option

### Documentation Page
- Getting started guide
- API reference (POST /shorten, GET /{code}, GET /stats/{code})
- Rate limits and usage policies
- FAQ section

### Design Requirements
- Modern, clean aesthetic (no generic AI look)
- Responsive design (mobile, tablet, desktop)
- Dark mode support
- Smooth animations and transitions
- Consistent color scheme and typography

## API Requirements
- POST /shorten: accepts { url: string, alias?: string }, returns { shortCode, shortUrl }
- GET /{shortCode}: redirects to original URL (301)
- GET /stats/{shortCode}: returns { originalUrl, clickCount, createdAt }

## Success Criteria
- All unit tests pass
- All integration tests pass
- pulumi preview shows no errors
- pulumi up deploys successfully

## End-to-End Verification (Required)
After deployment, use Playwright MCP to verify the live site:
1. Open the CloudFront URL and verify the landing page loads with all sections
1. Navigate to the docs page and verify content renders
1. Create a short URL using the dashboard
1. Verify the short URL redirects correctly (301 status)
1. Check the stats show the click was recorded
1. Test responsive design by resizing the viewport
1. Take screenshots of landing page, dashboard, and docs as proof

Only output <promise>COMPLETE</promise> after ALL of the above including E2E tests pass.

The key addition here is the end-to-end verification section. Without it, Claude reports success after pulumi up finishes, but you have no guarantee the deployed infrastructure actually works. By requiring Playwright to test the live URLs, you catch issues like the CloudFront 403 error I mentioned earlier.

Before running the loop, I started Claude Code with permission bypass mode to prevent it from stopping to ask for approval on every file write or command:

claude --permission-mode bypassPermissions

There are other ways to handle permissions, but this is the simplest for autonomous execution. Then I ran the Ralph loop:

/ralph-wiggum:ralph-loop PROMPT.md --max-iterations 25 --completion-promise "COMPLETE"

Then I stepped away and let it run unsupervised. For complex projects, you could even let it run overnight while you sleep.

Here is Claude Code in action during the Ralph loop, fixing CloudFront configuration issues and writing unit tests:

The results

The complete source code for this project is available on GitHub: url-shortener-saas

When Claude finished, it had:

Successfully built:

A complete Pulumi program with proper resource organization
DynamoDB table with a GSI for querying by creation date
Three Lambda functions with proper error handling
API Gateway with CORS configuration
S3 bucket with static website hosting
CloudFront distribution with proper cache behaviors

The frontend was genuinely impressive:

A polished landing page with hero section, feature cards, and pricing tiers
Working testimonials section with three fictional but believable customer reviews
A functional dashboard where you could create and manage short URLs
A documentation page with API reference and getting started guide
Dark mode toggle that actually worked
Responsive design that looked good on mobile

Home screen

Dashboard

Documentation

Here is a snippet of what it generated:

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

const stack = pulumi.getStack();
const projectName = "url-shortener";

// DynamoDB Table
const urlTable = new aws.dynamodb.Table("url-table", {
 name: `${projectName}-urls-${stack}`,
 billingMode: "PAY_PER_REQUEST",
 hashKey: "shortCode",
 attributes: [{ name: "shortCode", type: "S" }],
 tags: {
 Environment: stack,
 Project: projectName,
 ManagedBy: "Pulumi",
 },
});

// Lambda function for URL shortening
const shortenFunction = new aws.lambda.Function("shorten-function", {
 name: `${projectName}-shorten-${stack}`,
 runtime: aws.lambda.Runtime.NodeJS20dX,
 handler: "shorten.handler",
 role: lambdaRole.arn,
 timeout: 30,
 memorySize: 256,
 code: new pulumi.asset.AssetArchive({
 ".": new pulumi.asset.FileArchive("./lambda"),
 }),
 environment: {
 variables: {
 TABLE_NAME: urlTable.name,
 },
 },
});

// CloudFront Distribution with S3 and API Gateway origins
const distribution = new aws.cloudfront.Distribution("frontend-distribution", {
 enabled: true,
 defaultRootObject: "index.html",
 origins: [
 {
 domainName: frontendBucketWebsite.websiteEndpoint,
 originId: "S3Origin",
 customOriginConfig: {
 httpPort: 80,
 httpsPort: 443,
 originProtocolPolicy: "http-only",
 originSslProtocols: ["TLSv1.2"],
 },
 },
 {
 domainName: pulumi.interpolate`${api.id}.execute-api.${aws.config.region}.amazonaws.com`,
 originId: "APIGatewayOrigin",
 customOriginConfig: {
 httpPort: 80,
 httpsPort: 443,
 originProtocolPolicy: "https-only",
 originSslProtocols: ["TLSv1.2"],
 },
 },
 ],
 defaultCacheBehavior: {
 targetOriginId: "S3Origin",
 viewerProtocolPolicy: "redirect-to-https",
 allowedMethods: ["GET", "HEAD", "OPTIONS"],
 cachedMethods: ["GET", "HEAD"],
 forwardedValues: {
 queryString: false,
 cookies: { forward: "none" },
 },
 },
 orderedCacheBehaviors: [{
 pathPattern: "/api/*",
 targetOriginId: "APIGatewayOrigin",
 viewerProtocolPolicy: "https-only",
 allowedMethods: ["DELETE", "GET", "HEAD", "OPTIONS", "PATCH", "POST", "PUT"],
 cachedMethods: ["GET", "HEAD"],
 forwardedValues: {
 queryString: true,
 headers: ["Authorization", "Content-Type"],
 cookies: { forward: "none" },
 },
 minTtl: 0,
 defaultTtl: 0,
 maxTtl: 0,
 }],
 viewerCertificate: {
 cloudfrontDefaultCertificate: true,
 },
});

Where it struggled:

The first few iterations had the Lambda code inline instead of in separate files
It initially forgot to set up IAM permissions for the Lambda to access DynamoDB
The CloudFront configuration took three attempts to get the cache behaviors right

The funny parts:

At iteration 12, it decided to completely refactor the project structure. Then at iteration 13, it refactored it back
One commit message simply read: “fix the fix that fixed the previous fix”
It wrote a test, ran the test, fixed the code to pass the test, then realized the test was wrong

Pair your coding agent with Pulumi

You can point Claude Code, Cursor, Codex, or any coding agent at Pulumi through the Pulumi MCP server and Agent Skills, and let infrastructure as code give it objective success criteria. Start a project to try it.

Get started

Best practices for Ralph with Pulumi

After running several experiments, here is what I have learned:

Write extremely specific prompts. Vague instructions lead to vague implementations. Be explicit about every requirement, every edge case, every success criterion.

Use pulumi preview as your feedback loop. Add this to your success criteria:

Success Criteria:
- pulumi preview completes with no errors
- pulumi preview shows expected resource count (approximately X resources)

Set realistic iteration limits. For infrastructure projects, I have found 20-30 iterations is usually sufficient. More than that and you are probably missing something in your prompt.

Include test requirements. Claude is surprisingly good at test-driven development when you tell it to write tests first:

## Development Approach
1. Write unit tests for each Lambda function first
1. Implement Lambda functions to pass the tests
1. Write integration tests that verify the deployed infrastructure
1. Only output COMPLETE when all tests pass

Mention cost awareness. Add a note like “Use PAY_PER_REQUEST billing for DynamoDB” or “Use the smallest Lambda memory allocation that works.” Claude will optimize for what you tell it to optimize for.

The honest assessment

Is this the future of infrastructure development? Probably not entirely. But it is a genuinely useful technique for specific scenarios:

Great for:

Greenfield projects where you have clear requirements
Large migrations or refactors
Building proof-of-concept infrastructure while you focus on other work
Tasks where iteration is more valuable than perfection on the first try

Not great for:

Production infrastructure changes (please do not let an AI modify your production AWS account unsupervised)
Complex architecture decisions that require human judgment
Anything involving sensitive data or security configurations
Small tweaks or quick fixes (overkill)

The API costs were reasonable for what I got. For a complete infrastructure project built autonomously, a few dollars in Claude API calls is a bargain compared to my hourly rate.

Try it yourself

If you want to experiment with Ralph Wiggum and Pulumi:

Install Claude Code and the Ralph Wiggum plugin
Set up your Pulumi account and AWS credentials
Write a detailed PROMPT.md with clear success criteria
Start with a small project and low iteration limits
Review the git history when it finishes

The combination of autonomous AI loops and infrastructure as code feels like a glimpse of where development is heading. Not replacing developers, but changing how we use our time. Instead of babysitting an AI through each step, you hand it a well-defined problem and come back to working infrastructure.

Just make sure you have billing alerts set up. Ralph Wiggum does not know when to stop spending your money.

Or try Pulumi Neo: Ralph built-in

If setting up the Ralph Wiggum plugin feels like too much ceremony, Pulumi has something similar built right into Pulumi Neo.

Neo Tasks work on the same principle: you describe what you want, and Neo plans and executes the infrastructure changes. The key is auto mode. When you set a task to auto mode, Neo runs without requesting approvals. It plans, executes, validates with pulumi preview, and iterates until the task is complete.

The experience is remarkably similar to Ralph:

Persistent execution: Tasks continue running even if you close your browser. Come back later and Neo shows you what it accomplished while you were away.
Iterative refinement: Failed deployments inform the next attempt, just like Ralph re-reading the project state.
Clear completion: Neo knows when the infrastructure matches your requirements.

The main difference is that Neo runs in Pulumi Cloud rather than on your local machine, and it is purpose-built for infrastructure tasks. You get the autonomous loop experience without needing to configure plugins or bash loops.

For teams already using Pulumi Cloud, Neo with auto mode might be the fastest path to autonomous infrastructure development.

Resources

Pulumi + Bun: Supercharge Your Infrastructure Dependencies

Piers Karsenbarg — Mon, 28 Jul 2025 09:50:26 +0100

Today, we are announcing a new addition that allows Pulumi users to use Bun as their package manager, offering an alternative to npm, Yarn, or pnpm. Bun, a recently released JavaScript runtime, bundler, transpiler, and package manager, provides a faster way to manage Pulumi project dependencies.

What is this Bun thing you’re talking about?

If you’ve spent time around the JavaScript ecosystem, then you’ve probably heard of Bun. If you haven’t, then be aware that it presents itself as a JavaScript toolkit, a direct drop-in replacement for NodeJS. However, the part that we like at Pulumi is its use as a package manager. According to the Bun install documentation, switching from npm install to bun install can make your installations up to 25 times faster.

Pulumi uses Bun solely as a package manager. You cannot use Bun to write Automation API-based applications, nor do we have a language plugin for Bun.
This requires Bun version 1.2 or greater due to the text-based lockfile introduced in this version.

Getting started with Bun and Pulumi

If you’re already using NodeJS with Pulumi, the easiest way to install Bun is to run the following:

npm install -g bun

The Bun installation documentation has more information on other methods available.

How to use in a new project

If you want to try this out on a new project, you can use

mkdir new-bun-project && cd new-bun-project
pulumi new typescript

You’ll get the usual prompts to set the project name, the description, and the stack name:

This command will walk you through creating a new Pulumi project.

Enter a value or leave blank to accept the (default), and press <ENTER>.
Press ^C at any time to quit.

Project name (new-bun-project):
Project description (A minimal TypeScript Pulumi program):
Created project 'new-bun-project'

Please enter your desired stack name.
To create a stack in an organization, use the format <org-name>/<stack-name> (e.g. `acmecorp/dev`).
Stack name (dev):

Then you’ll be shown a list of the package managers to choose from (obviously we’ll use the arrow keys to select the bun option):

The package manager to use for installing dependencies [Use arrows to move, type to filter]
 npm
 pnpm
 yarn
> bun

Hit the ENTER key to make your selection, and you’ll see the bun install output:

The package manager to use for installing dependencies bun
Installing dependencies...

bun install v1.2.18 (0d4089ea)

+ @types/node@18.19.120 (v24.1.0 available)
+ typescript@5.8.3
+ @pulumi/pulumi@3.186.0

272 packages installed [1240.00ms]

Blocked 1 postinstall. Run `bun pm untrusted` for details.
Finished installing dependencies

Your new project is ready to go! ✨

To perform an initial deployment, run `pulumi up`

The files in the folder look a little different:

drwxr-xr-x@ - piers 28 Jul 18:13 node_modules
.rw-r--r--@ 21 piers 28 Jul 18:11 .gitignore
.rw-r--r--@ 61k piers 28 Jul 18:13 bun.lock
.rw-r--r--@ 42 piers 28 Jul 18:11 index.ts
.rw-r--r--@ 217 piers 28 Jul 18:11 package.json
.rw-r--r--@ 198 piers 28 Jul 18:13 Pulumi.yaml
.rw-r--r--@ 438 piers 28 Jul 18:11 tsconfig.json

(note the bun.lock instead of the package-lock.json)

and in the Pulumi.yaml file, the packagemanager option is set to bun:

name: new-bun-project
description: A minimal TypeScript Pulumi program
runtime:
name: nodejs
options:
packagemanager: bun
config:
pulumi:tags:
value:
pulumi:template: typescript

We will use the Random provider to generate a new password. Let’s add the @pulumi/random package:

❯ bun add @pulumi/random
bun add v1.2.18 (0d4089ea)

installed @pulumi/random@4.18.3

[345.00ms] done

Since we’re still using the Pulumi NodeJS runtime, that’s all we need Bun for right now.

The rest is business as usual, so the index.ts file looks like:

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

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

export const pw = password.result;

Then it’s just a case of running:

pulumi up

and creating the resources.

Migrating an existing project

If you already have a project set up and are using npm as your package manager, there are a few steps you’ll need to follow.

For this example, I’m going to use the code from the Bun example above but set it up using npm instead:

❯ pulumi new typescript
This command will walk you through creating a new Pulumi project.

Enter a value or leave blank to accept the (default), and press <ENTER>.
Press ^C at any time to quit.

Project name (migrate-project):
Project description (A minimal TypeScript Pulumi program):
Created project 'migrate-project'

Please enter your desired stack name.
To create a stack in an organization, use the format <org-name>/<stack-name> (e.g. `acmecorp/dev`).
Stack name (dev):

The package manager to use for installing dependencies npm
Installing dependencies...


added 293 packages, and audited 294 packages in 9s

43 packages are looking for funding
 run `npm fund` for details

found 0 vulnerabilities
Finished installing dependencies

Your new project is ready to go! ✨

To perform an initial deployment, run `pulumi up`

Then we’ll install the @pulumi/random package:

npm install @pulumi/random

and checking the folder listing:

drwxr-xr-x@ - piers 28 Jul 18:32 node_modules
.rw-r--r--@ 21 piers 28 Jul 18:32 .gitignore
.rw-r--r--@ 42 piers 28 Jul 18:32 index.ts
.rw-r--r--@ 149k piers 28 Jul 18:32 package-lock.json
.rw-r--r--@ 217 piers 28 Jul 18:32 package.json
.rw-r--r--@ 198 piers 28 Jul 18:32 Pulumi.yaml
.rw-r--r--@ 438 piers 28 Jul 18:32 tsconfig.json

we can see that we’ve got the usual package-lock.json file that we expect, and the Pulumi.yaml file looks like this:

name: migrate-project
description: A minimal TypeScript Pulumi program
runtime:
name: nodejs
options:
packagemanager: npm
config:
pulumi:tags:
value:
pulumi:template: typescript

(Note the packagemanager option).

To migrate this project to use Bun as the package manager instead, we need to update the Pulumi.yaml to set the packagemanager to be bun:

name: migrate-project
description: A minimal TypeScript Pulumi program
runtime:
name: nodejs
options:
packagemanager: bun
config:
pulumi:tags:
value:
pulumi:template: typescript

We can use the bun CLI to migrate the package-lock.json file to the bun.lock file, running the following command:

bun pm migrate

which gives us the file structure:

drwxr-xr-x@ - piers 28 Jul 18:32 node_modules
.rw-r--r--@ 21 piers 28 Jul 18:32 .gitignore
.rw-r--r--@ 64k piers 28 Jul 18:43 bun.lock
.rw-r--r--@ 42 piers 28 Jul 18:32 index.ts
.rw-r--r--@ 149k piers 28 Jul 18:32 package-lock.json
.rw-r--r--@ 217 piers 28 Jul 18:32 package.json
.rw-r--r--@ 198 piers 28 Jul 18:32 Pulumi.yaml
.rw-r--r--@ 438 piers 28 Jul 18:32 tsconfig.json

We can then delete the package-lock.json if we want to.

Then we can run pulumi install to install the packages to Bun’s global cache:

❯ pulumi install
Installing dependencies...

bun install v1.2.18 (0d4089ea)

15 packages installed [60.00ms]
Finished installing dependencies

and continue with

pulumi up

What else?

We’ve baked Bun into the pulumi/pulumi container, allowing you to make use of the faster package installer in your CI/CD pipeline, including in Pulumi Deployments. If you’d like to see Bun become more integrated into Pulumi, there’s an open issue that you can vote on, or even implement if you’re interested.

Final thoughts

Bun is in the process of establishing itself as the new player in the JavaScript ecosystem. Its focus on speed makes it a great alternative to npm, Yarn, and pnpm when managing Pulumi project dependencies. Give it a try on your next project, and you may wonder how you ever lived without it.

Next-level IaC: Bridging the Declarative Gap

Troy Howard — Fri, 07 Jun 2024 00:00:00 +0000

Pulumi stands out in the world of infrastructure-as-code (IaC) for its flexibility and ease of use. This is due to its unique approach of using general purpose programming languages to describe system configuration. It accomplishes this through a small but brilliant implementation detail that bridges the worlds of declarative and standard programming using asynchronous semantics.

Since this post was published, Pulumi has added first-class support for HashiCorp Configuration Language (HCL). You can now write Pulumi programs in HCL directly, alongside general-purpose languages like TypeScript, Python, Go, and C#. To see how it works, see Pulumi HCL.

In Pulumi, you describe your infrastructure in code – real code, not a DSL or YAML – using your preferred general purpose programming language. You don’t have to become a specialist in a niche proprietary declarative language, like Terraform’s HCL. Rather, you can reuse your existing programming skills, writing in standard imperative, object-oriented, and even functional language styles, while still gaining all of the benefits of the declarative style that other tools emphasize.

Pulumi provides a unique mix of a declarative model embedded and implemented inside of a standard programming language, allowing all the flexibility of custom imperative code, while still enabling Pulumi’s deployment engine to infer opportunities for parallel asynchronous execution and to converge a partially-realized system.

The secret sauce that lets Pulumi achieve this is the apply function, and the way it handles inputs and outputs via asynchronous programming constructs, similar to futures or promises. We’ll go deeper on that in this article, but first let’s talk a little bit about the flow of operations in Pulumi.

Pulumi’s architecture and flow of operations

Pulumi is a system that is made up of a number of components. At a high level, those are:

Pulumi Programs: The code you write to describe the infrastructure you need.
Deployment Engine: A process that executes requests to create/modify infrastructure.
Resource Providers: Plugins that interface with cloud services like AWS, Azure, and others.

These components interact together to manage your infrastructure across multiple cloud providers using a consistent programming and execution model.

Figure: Pulumi’s Program, Deployment Engine, and Resource Provider architecture

Let’s get into an example of how information flows back and forth between these components. Suppose you want to write a Pulumi program to create an AWS S3 Bucket to host a static website. When that bucket is created, it will be given a unique identifier that you need to use in other parts of your infrastructure. Every time you create the bucket the identifier will change, and it’s generated by the AWS API, so we can’t know it ahead of time. We need to handle this as a variable, not a fixed configuration value.

To do that in a Pulumi program, you can create a bucket and then refer to its id property later, like this:

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

// Create an S3 bucket
const bucket = new aws.s3.Bucket("bucket");

// Export the name of the bucket
export const bucketName = bucket.id;

import pulumi
import pulumi_aws as aws

# Create an S3 bucket
bucket = aws.s3.Bucket('bucket')

# Export the name of the bucket
pulumi.export('bucket_name', bucket.id)

When this program runs, the call to create the bucket object will issue a request to the deployment engine. The deployment engine will load the resource provider for AWS, and ask it to create the S3 bucket. The AWS resource provider then issues the request to the AWS API, which will create the bucket and then return the id of the newly created resource. The provider will return that to the deployment engine, which will then set the realized value on your Pulumi program’s bucket.id property and then move on to creating anything that depends on that property.

This all seems pretty straight-forward, except that Pulumi programs don’t wait and imperatively do each operation, one at a time. Instead the deployment engine will run them in parallel, only waiting in cases where the output of one operation is needed to run the next operation. This can create complex structures with some operations needing to wait for inputs from other operations, and some that don’t, all finishing at different times, depending on how long the cloud service takes to process that request.

Inputs and Outputs as asynchronous futures

Infrastructure automation tasks can be long-running and can result in intermittent errors and may need to be retried before moving on to the next step. A robust IaC solution will need to run concurrently, be able to restart, retry, and resume itself, and understand that a set of tasks could happen in any order, not necessarily in the order you defined them in code.

Back in our Pulumi program code, that means that some of the time the bucket object from our earlier example has its id property set, and sometimes it doesn’t. We wouldn’t want to run any operation that needed that variable before it was set, but we also wouldn’t want to wait to start operations that don’t need that value.

To address this, Pulumi models the input and output values as futures. This allows you to describe a complex set of needs using a familiar value-like syntax. Instead of using a string result directly, which would only exist some of the time, you instead work with an Output<string>, that Pulumi understands as a reference to a value that currently doesn’t exist, but will exist when the operation completes. Similarly, Input<string> describes a dependency on an input string that will at some point be provided as the result of another operation.

This notion of future completion is essential to understanding why apply blocks are necessary within Pulumi programs. The apply function is called by the deployment engine only when the operation has completed and the fully realized value is available. By using Input<T> and Output<T> to build the connections between different parts of your infrastructure, the code is leveraging asynchronous value semantics not just to wrap and provide access to a future value, but also to describe a relationship between two components. This allows Pulumi programs to be very natural to author and as readable as traditional code, while also enabling Pulumi’s deployment engine to execute the entirety of your graph of operations in parallel, only waiting when necessary. This maximizes the efficiency of interacting with potentially slow and unreliable external cloud services.

Realizing values using the `apply` function

An important distinction though, is that Input<T>/Output<T> values are just declarative placeholders for the values that will eventually be present. At a certain point you will need to access the values directly, for example in the context of a transformation. The output of one operation might produce a string, which you need to transform into another data structure before passing to the next operation. Pulumi really shines in this context!

Using the apply function we can pass an Input<T> or Output<T> to a transformation function which will accept the realized value as its input (and only run when that value is available). Within that function you can handle the string as a normal string, then return it back as an Output<string>. This allows you to use the full power of your programming language to perform a custom operation inline with the rest of your infrastructure automation.

Here’s a simple example of using apply to transform an output to something new using your programming language’s libraries. In this case, Base64 encoding the id of our bucket object.

Example: Using `apply` to Base64 encode an Output

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

// Create an S3 bucket
const bucket = new aws.s3.Bucket("bucket");

// Export the name of the bucket
export const bucketName = bucket.id;

// Export the name of the bucket, in Base64 encoding
export const bucketNameBase64 = bucket.id.apply(id=> {
 // Transform the bucket name into a Base64 encoded string
 Buffer.from(id).toString('base64')
})

import base64
import pulumi
import pulumi_aws as aws

# Create an S3 bucket
bucket = aws.s3.Bucket('bucket')

# Export the name of the bucket
pulumi.export('bucket_name', bucket.id)

# A Base64 encoder function to use in the apply function's lambda
def base64_encode(data):
 data_bytes = data.encode("ascii")
 base64_bytes = base64.b64encode(data_bytes)
 base64_string = base64_bytes.decode("ascii")

# Export the name of the bucket, in Base64 encoding
pulumi.export('bucket_name', bucket.id.apply(lambda data: base64_encode))

Our example shows how to do Base64 encoding, but this technique can be used for any kind of transformation function. These can be as elaborate as your use case requires, and leverage the full power of your programming language and its entire ecosystem. Doing custom transformations like this in other popular tools is often not possible. This leaves you stuck using external coordination (e.g. gluing things together with Bash scripts) which breaks their declarative-only model (because you cannot describe everything you need to do in it) and interrupts these tools’ ability to fully understand your infrastructure’s dependency graph.

While Pulumi’s asynchronous semantics may seem somewhat complex for basic use cases, they unlock abilities in more complex use cases, which is when you really need your IaC tooling to show up for you. Because real life is never as simple as demo code.

Next steps

If you haven’t already, install Pulumi today, and follow our self-directed Getting Started guides to learn more about making the most of Pulumi’s next-level infrastructure management features at your organization.

To learn more, you can watch the following video which provides a high level overview of how Pulumi works:

*{padding:0;margin:0;overflow:hidden}html,body{height:100%}img{position:absolute;width:100%;top:0;bottom:0;margin:auto}">

Pulumi Cloud

The Pulumi Cloud is a fully managed service that helps you adopt Pulumi’s open source SDK with ease. It provides built-in state and secrets management, integrates with source control and CI/CD, and offers a web console and API that make it easier to visualize and manage infrastructure. It is free for individual use, with features available for teams.

Create an Account

Next-level IaC: Breakpoint Debugging for Pulumi Programs

Troy Howard — Fri, 31 May 2024 00:00:00 +0000

For many of us, life is suspended between presses of the F5 key. Our IDE is the only place where everything is organized and makes sense. And while we know that the likelihood of a code hole-in-one is very rare (that magical moment where you run your build and everything just works the first time), we always hope that this time, this will be the run where you see the output that lets you know you’ve gotten it right. And in between? Debugging.

Debugging is a complicated topic. But what is not complicated is understanding the cost of debugging. Debugging is the biggest unknown-unknown in software. It makes you miss your sprint goals, it holds back scaling and company growth, it slows your time to market. Debugging is what makes estimating so difficult, because until you know what the problem is, you don’t know how long it will take to fix, or indeed if it is even possible to fix at all. Which is why savvy developers invest a lot of time into refining their debugging process and seek out the best-in-class tools to streamline this process.

In the infrastructure world, debugging is a pretty big problem. Some of the most popular tools have nothing more than simple unstructured text output logs. While tools like Terraform call themselves “Infrastructure as Code” the “code” is a proprietary DSL, not a general purpose programming language, and so there is little-to-no IDE support. There is no F5. Even worse, there is no F9 for setting a breakpoint. There’s no way to inspect state mid-run, or more importantly to explore in an unstructured way, because this is where the “aha!” moments usually happen.

Pulumi gives you a rich IaC debugging experience by enabling breakpoint debugging in your favorite IDE. Let’s walk through an example of how to enable a full-featured debugging workflow in VS Code for TypeScript.

How Breakpoint Debugging Works

Using a debugger can feel like that moment in The Matrix where Neo first sees the green streaming code raining down. A debugger lifts the veil from your otherwise opaque executable code. Tools like VS Code provide a user experience where you set breakpoints, i.e. certain lines of code that are designated as points where you want to pause execution and inspect state. Hitting the F9 key in VS Code sets a breakpoint on the current line of code. Later, you run your code in debug mode. This is a special execution state where the underlying runtime (e.g. Node’s V8) exposes a TCP/IP port hosting a debugging protocol, and when run, it will pause execution until something attaches to it (i.e. connects to the port to start the debugging session).

At this point a debugging client (such as VS Code) will control the flow of the program, moving forward step-by-step, one line of code at a time. But how does it know which line of code it’s executing? When you run in debug mode, the binary code is instrumented with metadata about the line of code it represents. The debugger will tell the runtime, via the debugging protocol, “run until you reach line 109 in file data.ts, then pause and wait for a signal from me before continuing”.

While paused, the protocol also allows you to inspect the values of any variables that are in scope at that moment. A more sophisticated debugger will provide a REPL environment where you can execute ad-hoc code in the scope of the line where you are paused. This can be very powerful to inspect the values of various objects and to see in real-time what the effects of executing variations of code would be. After a debugging session you can take what you’ve learned and edit the code accordingly.

Example: Attaching a debugger to a TypeScript Pulumi program in VS Code

For this example, we will set up a new Pulumi project from the command-line and then set up VS Code to run that program in a debugger.

Step 1: Create a Pulumi project from a template

For this example, we will create a new Pulumi project using the TypeScript AWS static website template. Make sure you’ve set up Pulumi, logged into Pulumi Cloud, and configured your AWS credentials. Follow the prompts in the pulumi CLI to configure your project.

$ mkdir good-morning && cd good-morning
$ pulumi new static-website-aws-typescript

Then launch this project to make sure it works as expected:

$ pulumi up
...

Updating (dev)

View in Browser (Ctrl+O): https://app.pulumi.com/troy-pulumi-corp/good-morning/dev/updates/1

 Type Name Status
 + pulumi:pulumi:Stack good-morning-dev created (200s)
 + ├─ aws:s3:Bucket bucket created (1s)
 + ├─ aws:s3:BucketPublicAccessBlock public-access-block created (0.57s)
 + ├─ aws:s3:BucketOwnershipControls ownership-controls created (1s)
 + ├─ aws:cloudfront:Distribution cdn created (196s)
 + └─ synced-folder:index:S3BucketFolder bucket-folder created (0.41s)
 + ├─ aws:s3:BucketObject error.html created (0.46s)
 + └─ aws:s3:BucketObject index.html created (0.46s)

Outputs:
 cdnHostname : "##############.cloudfront.net"
 cdnURL : "https://##############.cloudfront.net"
 originHostname: "bucket-#######.s3-website-us-west-2.amazonaws.com"
 originURL : "http://bucket-#######.s3-website-us-west-2.amazonaws.com"

Resources:
 + 8 created

Great! You should be able to navigate to the website using the URL from the cdnURL output value.

$ open $(pulumi stack output cdnURL)

If all looks good, let’s move on to the next step by opening your project directory in VS Code:

$ code .

Step 2: Lets break stuff!

Now that we have a perfectly running Pulumi program, in order to have something to debug, we will need to break it!

For this example, we are going to change our indexDocument from index.html to good-morning.html.

$ cp ./wwww/index.html ./www/good-morning.html

Next, let’s edit the contents to say “Good morning, world!” instead of “Hello, world!”:

<!DOCTYPE html>
<html lang="en">
<head>
 <meta charset="utf-8">
 <title>Good morning, world!</title>
</head>
<body>
 <h1>Good morning, world! 👋</h1>
 <p>Deployed with 💜 by <a href="https://pulumi.com/">Pulumi</a>.</p>
</body>
</html>

Once that’s edited and saved, go ahead let’s redeploy the website:

$ pulumi up

Everything runs successfully… but if we navigate to the website, we don’t see our updated content?! Oh no! What went wrong? Why isn’t there an error message?! Time to put on our debugging hats and figure out what is going on. First, let’s set up VS Code to enable breakpoint debugging right in the IDE.

Step 3: Create a debug wrapper script

VS Code can run an arbitrary command when you hit F5. Typically this would be a one-liner that runs your language runtime like node foo.js or python foo.py. In our case, we need to run the pulumi CLI and need to do more than one step. The easiest way to do this is to create a small wrapper script and call that from VS Code.

In the root of the directory, create a file called pulumi-debug.sh:

#!/bin/bash

pulumi login
pulumi stack select dev
pulumi up -f

Let’s walk through these lines to explain what’s going on here:

pulumi login to set up credentials for the pulumi backend
pulumi stack select dev to run this against our dev stack
pulumi up -f to run our program update. The -f flag skips the preview phase and also skips the need to interactively confirm that we want to run the update.

Open the VS Code terminal panel and first set it to be executable, then try running the script:

$ chmod +x pulumi-debug.sh
$ ./pulumi-debug.sh

Ok now let’s set up VS Code to run that in debug mode when we hit F5!

Step 4: Configure VS Code `launch.json` and `tasks.json`

To run our Pulumi program in debug mode we will need to create a couple of VS Code configuration files, launch.json and tasks.json, in a hidden directory called .vscode within your project.

Create the .vscode directory and then create a new file called tasks.json file in that directory, with the following contents:

{
 "version": "2.0.0",
 "tasks": [
 {
 "label": "pulumi-debug",
 "type": "shell",
 "command": ". ./pulumi-debug.sh",
 "isBackground": true,
 "options": {
 "cwd": "${workspaceFolder}"
 }
 }
 ]
}

This creates a VS Code task named pulumi-debug which will run the wrapper script we just created from the root of our project.

Next, create a file named launch.json in the same directory. This will configure the behavior of the F5 key!

{
 "version": "0.2.0",
 "configurations": [
 {
 "name": "Launch Pulumi Program (debug)",
 "type": "node",
 "port": 9292,
 "request": "attach",
 "preLaunchTask": "pulumi-debug",
 "continueOnAttach": true,
 "restart": {
 "delay": 5000,
 "maxAttempts": 5
 },
 "skipFiles": [
 "${workspaceFolder}/node_modules/**/*.js",
 "${workspaceFolder}/lib/**/*.js",
 "<node_internals>/**/*.js"
 ]
 }
 ]
}

Let’s break this down a bit:

type: node tells VS Code that we are using the Node runtime
port: 9292 tells VS Code to attach the debugger to port 9292
request: attach tells VS Code that we want to attach to the debugger at launch
preLaunchTask: pulumi-debug tells VS Code to run the task we configured in tasks.json before we connect the debugger. This will run our pulumi-debug.sh script and then attach to the Node.js runtime
continueOnAttach: true tells VS Code to start running our code as soon as we attach to the waiting Node.js runtime (until we reach our first breakpoint that is, where it will pause and return control to the debugger client, aka VS Code)
restart: {...} configures VS Code to wait 5 seconds and then retry connecting, up to 5 times. This is here in case it takes a while for the Node.js runtime to start running. It’s unlikely, but possible!
skipFiles: {...} sets up some filters of files not to try to debug. This includes everything that is part of node’s internals, 3rdparty node modules, and other libraries. That way we don’t end up deep in someone else’s code unexpectedly and can just focus on our Pulumi program.
name sets a human-readable name which shows up in the drop down box in VS Code when you choose which [launch configuration][vs-code-launch-configs] to run.

Finally, we need to make one more edit to the pulumi-debug.sh file we created. Here we will pass the necessary options to the Node.js runtime to set it to run in debug mode.

Add the following line to the beginning of the file:

#!/bin/bash

export NODE_OPTIONS='--inspect-brk=127.0.0.1:9292'

pulumi login
pulumi stack select dev
pulumi up -f

The NODE_OPTIONS environment variable passes options to the Node.js V8 runtime. In this case, we are passing --inspect-brk which tells the Node.js runtime to run in debug mode, which will cause it to pause before running the code, until a debugging client connects to localhost on port 9292.

Ok, now we should be ready to run our Pulumi program from VS Code using the F5 key! Let’s give it a try. You should see Pulumi running inside of the “Terminal” tab. You will also see output indicating that it is waiting for a debugger to attach:

Debugger listening on ws://127.0.0.1:9292/########-####-####-####-############
For help, see: https://nodejs.org/en/docs/inspector
Debugger attached.
Waiting for the debugger to disconnect...

Step 5: Setting a debugging breakpoint

Now we can try setting a breakpoint in our code. Getting back to the problem at hand – our content doesn’t seem to be updating, despite no errors. Let’s start at the beginning, by investigating the inputs to our program, aka our configuration… at runtime!

Navigate to line 12 within the code and hit the F9 key. You’ll see a small red dot appear next to the line indicating that a breakpoint has been set. This line defines the bucket our program creates and seems like a good place to stop if we want to check the input configuration before we run the AWS S3 provider call.

Figure: A breakpoint set on line 12.

You can then run the program again using F5. When the execution of the code reaches the line it will pause there. At this point you can navigate around the code inspecting the state of the local variables, like you would in any other debugging session.

Let’s inspect the configuration variables. On the left side of the screen you’ll find a “Variables” panel listing all the local variables that are in scope.

Figure: Local variables displayed in the Variables side panel.

There’s also the “Debug” console which provides a REPL environment to navigate those variables and anything else that is in scope. You can run arbitrary functions here and see their output. In this case we can simply type the variable name at the prompt there, hit enter, and see the value. What’s great about the debug console is that Intellisense (e.g. using TAB to auto-complete) works here, so you can quickly navigate possible options.

Figure: Debug console tab completion and inspecting variable values.

In our case, we’re interested in the value of indexDocument variable. We can see that it is getting set to index.html… not good-morning.html. The Pulumi program didn’t error because index.html still exists. So we are still publishing our old index.html. That makes sense. A quick fix here is to modify index.ts and set the default to good-morning.html:

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";
import * as synced_folder from "@pulumi/synced-folder";

// Import the program's configuration settings.
const config = new pulumi.Config();
const path = config.get("path") || "./www";
const indexDocument = config.get("indexDocument") || "good-morning.html";
const errorDocument = config.get("errorDocument") || "error.html";

...

Ok, we edited the document, which fixes the program for future runs, but for the current run that we are debugging, indexDocument is still set to index.html. Let’s use the debug console to set the value to good-morning.html before we continue the run.

> indexDocument="good-morning.html`

The output in the debug window will show the new value, and if you hover over the inputs being passed to the bucket creation call, it will now show as good-morning.html:

Figure: Screenshots of debug console and editor window after changing the indexDocument variable

When you’re ready for the program to continue on, hit F5 once again and the program will resume operation, either until the program exits or until it reaches the next breakpoint. Optionally you can step through line-by-line using the F10 key. VS Code provides a variety of debug actions once the session is established.

Most importantly, check the published website and make sure we fixed the issue! You can find the cdnURL output in the Terminal tab and click on it from there to open the link.

Considerations and Limitations

Breakpoint debugging is a powerful tool for inspecting the state of your Pulumi program. However, there are some important limitations to consider:

Pulumi programs are only part of the story: This technique will let you inspect the program you authored, but it doesn’t give access to what’s happening with the Pulumi backend, the providers, or anything else outside of the program itself. You might find yourself needing to dig deeper to resolve a problem with the stack as a whole. Luckily there are other techniques we can use for that, which we will delve into in an upcoming post.
Inputs and Outputs are asynchronous futures: If you’ve used Pulumi before you will have encountered Input<T> and Output<T> values, which are a core function of the tool. However, at the time that the debugger hits a breakpoint on those values, they are likely not populated with their final value. That means you won’t be able to inspect them in the debugger very well. Instead, you will need to add an apply(...) or all(..) block to the code, and place the breakpoint on the materialized value within that block. This follows all the same rules as accessing those variables in code in a Pulumi program.
```
bucket.id.apply(id => {
 // NOTE: The `debugger` keyword automatically sets a breakpoint here
 // so you don't need to set it via the IDE.
 debugger
});
```
Limited integration with VS Code: Unfortunately our technique of running Pulumi in wrapper script as a backgrounded pre-launch task in VS Code leaves some things to be desired. It is different enough from the use case that VS Code had in mind for these features (e.g. interacting with a long-running tsc-watch or similar task) that making things “just work” is a little difficult. For example, we can’t easily report on errors in the “Problems” tab, and VS Code complains that a problem matcher is missing the first time you run it. VS Code can’t tell that the program finished and so you’ll have to manually stop the debugging session after Pulumi has completed (or wait for the retry/timeout to expire).

Despite these limitations, Pulumi with VS Code as your IDE provides a rich experience compared to trawlling through unstructured logs, or adding in console.log(...) calls to echo out ad-hoc debugging information (aka. printf debugging). Also, you can enable this for any language that Pulumi supports, and most popular IDEs support breakpoint debugging (e.g. Visual Studio, Webstorm, neovim, etc). Python, Go, and C# all have popular debuggers and IDEs that can be used in the same manner. Whatever your preferred IDE or language is, you can use their full range of breakpoint debugging features for your Pulumi programs.

Pulumi also offers detailed logging which can be used to look into the other aspects that breakpoint debugging doesn’t cover. In an upcoming article we’ll show how to use these tools as well. Until then, have fun spelunking through your code with your favorite IDE!

Next Steps

To learn more, you can watch the following video which provides a high level overview of how Pulumi works:

*{padding:0;margin:0;overflow:hidden}html,body{height:100%}img{position:absolute;width:100%;top:0;bottom:0;margin:auto}">

Pulumi Cloud

Create an Account

Next-level IaC: Powering Up Pulumi with Package Ecosystems

Troy Howard — Mon, 13 May 2024 00:00:00 +0000

Every experienced tech professional I know has a programming language they love. But is it the syntax and symbols that make it so loveable? Not really. It’s the community and package ecosystem surrounding the language that makes a real impact on your heart… and on your productivity!

If we look at some of the biggest success stories in tech — Python, Node.js, Ruby, Perl, and Go — the common thread between all of them is an extensive ecosystem of packages, libraries, modules (or whatever you decide to call them… ahem, Gems?!). A great language will allow you to build anything you can imagine, but a great ecosystem will have already written it for you, and made it available in a convenient to install-and-use package.

One of the amazing things about Pulumi is that it is built around general-purpose programming languages, and that means your Pulumi programs have access to the entire ecosystem of packages that come with each language. This is a stark difference between Pulumi and other infrastructure automation tools that use proprietary domain-specific languages with not much in the way of community around them. Some tools might allow you to write custom code, but they certainly don’t make it convenient, and still… you have to write it yourself, which just adds so much overhead to a project where your core concern isn’t writing that custom function, but rather shipping your own product on the infrastructure you are trying to automate.

The flexibility that Pulumi gives you, and the access to these powerful libraries of code, means your productivity can skyrocket when you get to write in your favorite language, using your preferred tools and the package ecosystem you already know, love, and rely on every day.

Let’s have a look at a concrete example where this package ecosystem can get you out of a tough spot.

Use Case: Determining S3 MIME types on-the-fly

A popular example of cloud infrastructure automation is creating an S3 bucket and pushing some files to it. This is a common task that many of us have had to do, and most infrastructure automation tools have a way to accomplish this.

Here’s one way to do that in Pulumi:

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

// Create an S3 bucket where we will upload the file.
const bucket = new aws.s3.Bucket("my-bucket", {
 // You can apply additional bucket settings here.
});

const filePath = "path/to/your/local/file.txt"; // Replace with the path to the file you want to upload

// Upload the file to the S3 bucket.
const bucketObject = new aws.s3.BucketObject("my-bucket-object", {
 bucket: bucket, // Reference to the bucket created above.
 key: "file.txt", // This will be the file's name in the bucket.
 source: pulumi.FileAsset(filePath), // Contents of the file.
 contentType: "text/plain", // MIME-type of the file. Adjust if you upload a different type of file.
});

// Export the name of the bucket
export const bucketName = bucket.id;

// Export the URL of the file in the S3 bucket
export const objectUrl = pulumi.interpolate`s3://${bucket.id}/${bucketObject.key}`;

import pulumi
import pulumi_aws as aws

# Create an S3 bucket
bucket = aws.s3.Bucket('my-bucket')

# The path to the file to upload to S3
file_path = "path/to/your/local/file.txt" # Replace with the path to the file you want to upload

# Upload the file to the S3 bucket
bucket_object = aws.s3.BucketObject('my-bucket-object',
 bucket=bucket.id, # Reference to the bucket created above.
 key='file.txt', # This will be the file's name in the bucket.
 source=pulumi.FileAsset(file_path),
 content_type='text/plain') # MIME-type of the file. Adjust if you upload a different type of file.

# Export the name of the bucket
pulumi.export('bucket_name', bucket.id)

# Export the URL of the file in the S3 bucket
pulumi.export('object_url', pulumi.Output.concat('s3://', bucket.id, '/', bucket_object.key))

However, something that stands out as a weak link here is the line:

contentType: "text/plain", // MIME-type of the file. Adjust if you upload a different type of file.

content_type='text/plain') # MIME-type of the file. Adjust if you upload a different type of file.

Yeah, hard-coding the MIME type for every file I need to upload is a not going to scale. In fact, I’m probably going to get a random directory full of files I need to iterate over, each with different file types, and it will change every time it runs, and we won’t know what type of file it is ahead of time.

Packages to the rescue!! Turns out that determining the MIME type of a file only involves importing a community-created module like mime-types in TypeScript, or using the mimetypes module from Python’s standard library, and a single function call to guess the MIME type:

import * as mime from 'mime-types'

// Detect the MIME type of the file
const mimeType = mime.lookup('path/to/your/local/file.txt');

import mimetypes

# Detect the MIME type of the file
mime_type, _ = mimetypes.guess_type('path/to/your/local/file.txt')

So, to work that into our Pulumi program from above, we only need to make a few small edits:

import * as pulumi from '@pulumi/pulumi';
import * as aws from '@pulumi/aws';
import * as mime from 'mime-types';

// Create an S3 bucket where we will upload the file.
const bucket = new aws.s3.Bucket("my-bucket", {
 // You can apply additional bucket settings here.
});

const filePath = "path/to/your/local/file.txt"; // Replace with the path to the file you want to upload

// Upload the file to the S3 bucket.
const bucketObject = new aws.s3.BucketObject("my-bucket-object", {
 bucket: bucket, // Reference to the bucket created above.
 key: "file.txt", // This will be the file's name in the bucket.
 source: pulumi.FileAsset(filePath), // Contents of the file.
 contentType: mime.lookup(filePath) || "application/octet-stream", // MIME-type of the file
});

// Export the name of the bucket
export const bucketName = bucket.id;

// Export the URL of the file in the S3 bucket
export const objectUrl = pulumi.interpolate`s3://${bucket.id}/${bucketObject.key}`;

import pulumi
import pulumi_aws as aws
import mimetypes

# Create an S3 bucket
bucket = aws.s3.Bucket('my-bucket')

# The path to the file to upload to S3
file_path = "path/to/your/local/file.txt" # Replace with the path to the file you want to upload

# Detect the MIME type of the file
mime_type, _ = mimetypes.guess_type(file_path)

# Upload the file to the S3 bucket
bucket_object = aws.s3.BucketObject('my-bucket-object',
 bucket=bucket.id, # Reference to the bucket created above.
 key='file.txt', # This will be the file's name in the bucket.
 source=pulumi.FileAsset(file_path),
 content_type=mime_type or 'application/octet-stream') # MIME-type of the file

# Export the name of the bucket
pulumi.export('bucket_name', bucket.id)

# Export the URL of the file in the S3 bucket
pulumi.export('object_url', pulumi.Output.concat('s3://', bucket.id, '/', bucket_object.key))

Well that was pretty straightforward, wasn’t it? Trying to do this in another tool might take all day to figure out the right way to implement it, but in Pulumi it worked exactly like you would expect it to, in no time at all.

It’s a real game-changer when you can just quickly grab something complicated like MIME typing from a package. But when you can’t, you’re going to be stuck figuring out how to write that functionality yourself, from scratch, using things like Bash and primitive data types, and then find yourself copy-pasting that stuff all over the place. All the while fully aware of how much time you’re wasting by having to do so. That’s a real pain! It’s the kind of pain most people managing infrastructure have been through before.

The possibilities are endless

What other packages can you imagine using in your infrastructure solutions? Maybe you could use the text-to-image library to generate an image badge for your website? Maybe use the crypto module to encrypt a file before uploading it to S3? Or possibly using octokit to check on the state of something in git before taking the next step in your automation?

Whatever you can do with code in your favorite language, you can do in Pulumi as part of your infrastructure automation. I’m not saying you should use cowsay to generate custom MOTD banners for your ssh logins, I’m just saying you could.

Next Steps

To learn more, you can watch the following video which provides a high level overview of how Pulumi works:

*{padding:0;margin:0;overflow:hidden}html,body{height:100%}img{position:absolute;width:100%;top:0;bottom:0;margin:auto}">

Pulumi Cloud

Create an Account

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.

How Elkjøp Nordic enables self-service infrastructure for developers

George Huang — Fri, 01 Jul 2022 00:00:00 +0000

At PulumiUP 2022, Tomas Jansson, software architect at Elkjøp Nordic, gave a presentation on how to enable developers to self-service infrastructure by using Pulumi’s Automation API.

Elkjøp Nordic is the leading consumer electronics retailer in the Nordics. The company sells consumer electronics, mobile phones, computers, white goods, domestic appliances, and services linked to these products both directly to consumers and to businesses. It is an omnichannel retailer and serves customers both online and through more than 400 stores. Elkjøp has retail outlets in Norway, Sweden, Finland and Denmark, and franchise operations in Greenland and Faroe Islands.

To support the company’s modernization strategy, Tomas developed a self-service infrastructure platform that would enable any developer to easily provision cloud infrastructure that uses approved resources and security practices. The goal was to empower teams at Elkjøp to increase their development velocity by using the cloud, while maintaining guardrails that uphold security and compliance.

Watch the full presentation below or read on to learn the highlights of his presentation:

The Problem: Balancing Agility and Governance

To achieve his goals, Tomas knew he had to solve the problem of balancing freedom with control. On the one hand, he wanted to foster the creativity of his developers and encourage innovation. He wanted his team to feel they were trusted and had the room to create the best solutions they could. On the other hand, he knew he had to maintain some control. Elkjøp needed to keep its applications secure. It also needed good governance so that teams can keep track of who is making changes. Tomas also wanted to limit the impact of deploying untested code. Code that was still being developed needed to be confined to the developer’s own environment. Finding the right balance between independence and control was paramount. Tomas believed this would result in great software and in developers who would enjoy their work.

The Solution: A Self-Service Infrastructure Platform

Tomas’ solution was to build a self-service infrastructure platform. Self-service infrastructure makes it possible for developers to easily access the infrastructure they need while limiting access to resources they don’t need. In effect, self-service infrastructure is a walled garden. Within the garden, developers have all the freedom they need. However, nothing they do affects what’s outside the wall. Code that causes unintended changes only affects them and no one else.

Tomas built an application that provides a “walled garden” of self-service infrastructure. Developers can create the environments they need, including an Azure resource group and a Kubernetes namespace, all through a graphical user interface. Developers can define whether the environment is for development, test or production. They can also assign values, such as which team members should have admin privileges to the associated GitHub repositories or who can contribute. From there, the platform handles provisioning and configuring all of these resources.

Here is an example that shows how a developer can create a repository simply by selecting a few parameters from a drop-down list.

Tomas determined that the best way to implement self-service infrastructure was with Pulumi and its Automation API. By using Pulumi, he could use standard programming languages to define infrastructure while using familiar software tools like IDEs and test frameworks. Pulumi also natively supports Azure and Kubernetes with 100% coverage of each provider’s APIs and same-day access to new features and updates. Finally, the Pulumi Automation API would enable him to program infrastructure automation directly into his application.

The Pulumi Automation API is a programmatic interface for running Pulumi programs without the Pulumi CLI. Automation API encapsulates the functionality of the CLI (pulumi up, pulumi preview, pulumi destroy, pulumi stack init, etc.) but with more flexibility since infrastructure operations can be controlled programmatically.

How the self-service infrastructure platform was built

Here is the workflow for the Elkjøp self-service infrastructure platform.

The self-service platform is a web application that runs the Pulumi Automation API on the server side. The application uses Pulumi to provision and configure every environment resource such as Azure resource groups, Kubernetes namespaces, service principals, and Kubernetes service accounts. Each environment comes with a Git repository that’s used by developers to manage their deployments. The Git repositories are the locus of each environment because they store everything needed to deploy changes such as infrastructure code and environment credentials.

Using the Pulumi Automation API, the application creates an Azure resource group, a team in both Azure AD and GitHub, and a new GitHub repository. The application then grants administrative access to the GitHub repo to members of the AD group. In addition to creating a Git repository for each environment, the application uses stack references for each Azure environment to inject the associated credentials into the GitHub Secret Store. These credentials are scoped to each GitHub environment so that developers can only work in their own environment. If a team has multiple environments, each environment has its own credentials so developers can’t, for example, deploy from a test environment to a production environment. Secrets are managed through the Pulumi Service.

Every new repository comes with Pulumi programs that developers can use to deploy their application. GitHub Actions initiate the deployment. When an action triggers, Pulumi reads the credentials that were generated by the self-service application, allowing Pulumi to deploy new Kubernetes or Azure resources to the environment.

Watch the demo

To illustrate how Elkjøp’s self-service platform works, Tomas presented a simplified demo application that’s based on Elkjøp’s production platform. The code for the application is available at https://github.com/mastoj/pulumi-automation-demo.

The demo is a TypeScript application that includes an API that provisions Azure and GitHub resources. Pulumi Automation API code is used to deploy new stacks by calling handler code, which is a Pulumi program that defines resources and outputs. The handler code can create Azure resource groups or GitHub repositories, and stack references are used so that outputs generated by the Azure resources can be stored in GitHub (e.g., resource group credentials).

Ready to dive into how this works in detail? Watch the demo in the video below starting around 10:20.

Next steps

After watching the demo of a self-service infrastructure platform, you can try it out for yourself by checking out the demo code. You can also learn more about Pulumi Automation API in our documentation.

If you’re new to Pulumi, then follow our getting started guide.

Test-Driven Infrastructure Development with Pulumi and Jest

Christian Nunciato — Mon, 13 Jun 2022 00:00:00 +0000

When I was a kid growing up in Southern California, there was a phone number you could call to find out what time it was. It was a local number, 853-1212 (easy to remember as the arrangement of the numbers on the keypad made a capital T), and I used it all the time, to set my watch, adjust the alarm clock, fix the display on the VCR. I don’t recall the last time I used it, probably sometime in the mid ’90s, but I do remember clearly the sound of the voice at the other end of the line.

Services like these were called speaking clocks (although I never called them that; to me, it was just “calling Time”), and they date back to the early 1930s or so. In the U.S., most were powered by a machine called an Audichron that used mechanical drums to play back the time of day, often with a little advertisement or the current temperature to go along with it.

By the mid-2000s, though, most of these locally run services had been shut down — by then, we had clocks baked into our phones — and today, only a handful of Audichrons survive. Thanks to the National Institute of Standards and Technology, however, you can still call a phone number to get the time, and while the voice might not be the same, and long distance rates will apply, it’s definitely there, and you can use it. So on the off chance you happen to find yourself with no idea what time it is and only an analog phone line in reach, fear not — old-school telephone tech has your back. For now. Assuming you remember the number.

Recalling all this stuff did make me wonder, though, what a more modern version of a speaking clock might look like. So in this post, we’re going to build one ourselves. We won’t use an actual phone number, but we will use Pulumi and AWS — and because we want to do it right, we’ll take a test-driven approach to developing the infrastructure with Jest, the JavaScript testing framework. We’ll use TypeScript and Node.js for everything, focus on unit tests, and when we’re done, we’ll have a single, serverless, browser-friendly HTTPS endpoint that returns an MP3 audio stream that speaks the current time.

Let’s get started.

Sketching it out

The first thing we’ll need is a runtime environment — someplace to run some server-side JavaScript that can render and deliver an audio file. Until recently, the easiest way to get an HTTP endpoint up and running on AWS has generally been with AWS Lambda and API Gateway, using Lambda to run the requisite code and API Gateway to expose the Lambda to the internet. Pulumi Crosswalk actually makes this really easy, too — but with the release of AWS Lambda Function URLs this April, we now have another option, one that doesn’t need API Gateway at all.

A Lambda Function URL is just what it sounds like: a URL that exposes a Lambda function. Specifically, it’s an AWS cloud resource that consists of a few properties that tell AWS whether to allow anonymous access to the function or to protect it with AWS IAM, and optionally, you can also provide a few cross-origin resource-sharing (CORS) rules to provide (or restrict) access by websites running on other domains.

For an app like this one, a Function URL is a good fit, as it’s simple, quick to deploy (and update), and it gives us all the control we need to get the job done. Architecturally, then, our little app will look something like this:

That about covers the infrastructure — but what about the sound?

As it happens, Google Translate offers a publicly accessible text-to-speech API that can, as long as you don’t overuse it, render a string to MP3 audio. We can use that API to generate the time-of-day message, tack the sound of a beep onto the end of it (for maximum nostalgic effect), and voilà: instant, infinitely scalable, cloud-native speaking clock.

Plan in place, we can kick things off by creating a new Pulumi project.

Create a new TypeScript project

Start by creating a new AWS TypeScript project in the usual way:

$ mkdir audichron-2022 && cd audichron-2022
$ pulumi new aws-typescript

Step through the prompts to create a new stack (you’ll only need one stack for this project), and when the new-project wizard completes, clear out the contents of index.ts entirely, as we’ll be building this program entirely from the ground up.

Install and configure Jest

Since we’re working with TypeScript, we can use ts-jest, which conveniently brings Jest along for the ride:

$ npm install ts-jest @types/jest --save-dev

Jest requires a bit of configuration, so add a new file at the root of the project, called jest.config.ts, with the following code:

import type { Config } from "@jest/types";

const config: Config.InitialOptions = {
 preset: "ts-jest",
};

export default config;

With Jest now installed and configured, and its helpers (like describe and expect) declared globally, you can create a new spec file to hold your tests. Add another file at the root of the project called index.spec.ts, and give it the following temporary content:

import "jest";

describe("My speaking clock", () => {
 it ("works", () => {
 expect(true).toBeTruthy;
 });
});

Lastly, in package.json, add a scripts block with a helper to make running the tests a little easier:

{
 "name": "audichron-2022",
 "devDependencies": {
 "@types/node": "^14",
 "ts-jest": "^28.0.3"
 },
 ...
 "scripts": {
 "test": "jest"
 }
}

Now run the tests, just to make sure you’ve got everything wired up correctly. If all goes well, you should see that the temporary spec we just added happily passes:

$ npm test

PASS ./index.spec.ts
 My speaking clock
 ✓ works

With that, it’s time to get to start writing some real tests.

Start with some failing tests

As devoted practitioners of test-driven development, we’re going to start by writing some unit tests — specifically, some failing unit tests that we can fix by writing the Pulumi code to make them pass.

Recall that our design requires just two cloud resources: a Lambda function and a Lambda function URL. For the function itself, we’ll use the high-level aws.lambda.CallbackFunction resource, one of my favorites for managing for Lambdas because it requires only one property: an inline JavaScript function to handle the event that triggers the Lambda.

For the URL resource — the eventual triggerer of that event — you’ll use an aws.lambda.FunctionURL configured to make the Lambda publicly accessible (i.e., available to anyone on the internet) and embeddable on any domain, making it easy, for example, to embed the URL as the src attribute of an HTML5 audio element.

So to get things going, we’ll need to:

Configure Pulumi to mock AWS resources. We’re writing unit tests, after all, and we want them to be fast, so we’ll need to prevent those tests from provisioning any real cloud infrastructure.
Import your Pulumi resource declarations — the function and the function URL — into index.spec.ts so you can reference them in tests.

In that light, replace the contents of index.spec.ts with the following code, which, after some setup to switch Pulumi into unit-testing mode, contains just one test: a check to make sure that the function URL is configured with the right authorizationType. I’ve included some comments to help explain what each line is doing:

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

describe("My speaking clock", () => {

 // Define the infra variable as a type whose shape matches that of the
 // to-be-defined resources module.
 // https://www.typescriptlang.org/docs/handbook/2/typeof-types.html
 let infra: typeof import("./resources");

 beforeAll(() => {

 // Put Pulumi in unit-test mode, mocking all calls to cloud-provider APIs.
 pulumi.runtime.setMocks({

 // Mock requests to provision cloud resources and return a canned response.
 newResource: (args: pulumi.runtime.MockResourceArgs): {id: string, state: any} => {

 // Here, we're returning a same-shaped object for all resource types.
 // We could, however, use the arguments passed into this function to
 // customize the mocked-out properties of a particular resource based
 // on its type. See the unit-testing docs for details:
 // https://www.pulumi.com/docs/iac/concepts/testing/unit
 return {
 id: `${args.name}-id`,
 state: args.inputs,
 };
 },

 // Mock function calls and return whatever input properties were provided.
 call: (args: pulumi.runtime.MockCallArgs) => {
 return args.inputs;
 },
 });
 });

 beforeEach(async () => {

 // Dynamically import the resources module.
 // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#dynamic_imports
 infra = await import("./resources");
 });

 describe("function URL", () => {

 it("is publicly accessible", (done) => {
 infra.timeURL.authorizationType.apply(authType => {
 try {
 expect(authType).toBe("NONE");
 done();
 } catch (err) {
 done(err);
 }
 });
 });
 });
});

We can’t quite run these tests just yet, though, as they rely on a module called resources that we haven’t yet defined. Let’s do that now by creating a new file, resources.ts, containing some stubs for the cloud resources we’ve elected to use:

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

export const timeFunction = new aws.lambda.CallbackFunction("time-function", {
 callback: () => {
 // Leave the callback implementation empty for now.
 },
});

export const timeURL = new aws.lambda.FunctionUrl("time-url", {
 functionName: timeFunction.name,
 authorizationType: "", // Leave this empty, too. (We want our first test to fail.)
});

Now run the tests, and you should see that the public-accessibility test fails — which shouldn’t be surprising, as we haven’t yet supplied an acceptable value:

$ npm test

FAIL ./index.spec.ts
 My speaking clock
 function URL
 ✕ is publicly accessible

 ● My speaking clock › function URL › is publicly accessible

 expect(received).toBe(expected) // Object.is equality

 Expected: "NONE"
 Received: ""

Now let’s turn that sad-looking ❌ into a ✅.

Make the tests pass

Update the FunctionUrl resource to change its authorizationType input to NONE (meaning for anonymous access, no authorization required):

export const timeURL = new aws.lambda.FunctionUrl("time-url", {
 functionName: timeFunction.name,
- authorizationType: "",
+ authorizationType: "NONE",
});

Once you do that, you should be able to run the test suite again, and this time, see it pass:

$ npm test

PASS ./index.spec.ts
 My speaking clock
 function URL
 ✓ is publicly accessible

Excellent: you’re now well on your way to writing more tests with Jest — and we’ll do that in a moment. But first, let’s digress momentarily to explore a few other ways of writing Jest specs with Pulumi.

Tidy up the specs

If you’ve written JavaScript tests before, particularly with tools like Jest, Jasmine, and Mocha, there’s a good chance you’ve gotten used to writing those tests in a particular way. And if you’re like me, you might’ve raised a bit of an eyebrow when you saw how that first test was written. Here it is again, this time with comments that capture the questions I might’ve had myself if I were seeing this code for the first time:

it("is publicly accessible", (done) => {
 infra.timeURL.authorizationType.apply(auth => { // Why do I have to use .apply() here?
 try { // What happens if I don't try/catch?
 expect(auth).toBe("NONE"); // Is it possible to use expect() by itself?
 done(); // Do I have to call done()? What if I don't?
 } catch (err) { // How can I make these tests more readable?
 done(err); // Is all of this code necessary?
 }
 });
});

This is a perfectly valid test, of course; we know because we just ran it. Still, you might wonder, especially since we’re only checking one property, whether this test might be written a bit more concisely — something more like this, maybe:

it("is publicly accessible", () => {
 expect(infra.timeURL.authorizationType).toBe("NONE"); // Alas, nope.
});

The main reason is the asynchronous nature of the objects we’re testing. An aws.lambda.FunctionUrl, after all, isn’t just a plain ol’ JavaScript object — it’s a Pulumi CustomResource, a representation of an eventual resource running in the cloud, with properties that may not be known until sometime after the resource has been deployed. While it’s true we provided authorizationType as a regular JavaScript string, by the time we attempt to read it in the test, it’s been transformed into a pulumi.Output<string> — an asynchronous value, like a promise, that has to be unwrapped with a call to apply() before it can be read.

However, just adding apply and calling expect from within its callback doesn’t quite work, either:

it("is publicly accessible", () => {
 infra.timeURL.authorizationType.apply(authType => {
 expect(authType).toBe("NONE"); // Also nope.
 });
});

Although that might not be obvious at first, since on the surface, the test appears to pass:

$ npm test

PASS ./index.spec.ts
 My speaking clock
 function URL
 ✓ is publicly accessible

It isn’t until you force the test to fail that it becomes clearer something’s gone sideways. Try changing the expected authorizationType to something other than NONE and you’ll see what I mean:

$ npm test

PASS ./index.spec.ts
 My time app
 function URL
 ✓ is publicly accessible

Test Suites: 1 passed, 1 total
Tests: 1 passed, 1 total

[UnhandledPromiseRejection: This error originated either by throwing inside of an async function
without a catch block, or by rejecting a promise which was not handled with .catch(). The promise
rejected with the reason "Error: expect(received).toBe(expected) // Object.is equality

Expected: "AWS_IAM"
Received: "NONE"".] {
 code: 'ERR_UNHANDLED_REJECTION'
}

All is not lost, though. We do have other options, and that UnhandledPromiseRejection offers a bit of a clue.

Turn outputs into promises

Jest actually has built-in support for writing asynchronous tests with promises, and there are a couple of ways you can write specs that use them:

Have the function passed to it (or its alias, test) return a promise containing your expectation
Pass an async function to it and await the promise in the usual way

There’s only one problem: pulumi.Outputs may indeed be promise-like, but they aren’t actual promises.

They can, however, be wrapped in promises pretty easily. I like the way Pulumi community member @aviflax handled this with a little utility function that wraps the Output and preserves the type of its underlying value. Here’s that function, followed by a couple of examples that use it:

// Convert a pulumi.Output to a promise of the same type.
function promiseOf<T>(output: pulumi.Output<T>): Promise<T> {
 return new Promise(resolve => output.apply(resolve));
}

// Our test, rewritten to have it() return a Promise<string>.
it("is publicly accessible", () => {
 return promiseOf(infra.timeURL.authorizationType).then(authType => {
 expect(authType).toBe("NONE");
 });
});

// The same test, rewritten to use async/await.
it("is publicly accessible", async () => { // <-- Don't miss that async!
 const authType = await promiseOf(infra.timeURL.authorizationType);
 expect(authType).toBe("NONE");
});

Either approach works equally well, but I’m slightly more partial to the latter for its conciseness. So for now, update index.spec.ts to add the promiseOf helper and adjust the test accordingly, then run the suite one more time to make sure all’s well:

// ...

// Convert a pulumi.Output to a promise of the same type.
function promiseOf<T>(output: pulumi.Output<T>): Promise<T> {
 return new Promise(resolve => output.apply(resolve));
}

describe("My speaking clock", () => {
 // ...

 describe("function URL", () => {

 it("is publicly accessible", async () => {
 const authType = await promiseOf(infra.timeURL.authorizationType);
 expect(authType).toBe("NONE");
 });
 });
});

Assuming you’re back in ✅ territory, let’s move on so we can finish things off.

Finish the app

We’re in good shape: we’ve got scaffolding for our Jest-powered unit tests and we’re generally happy with how they look, so it’s time to round out the rest of the app and its tests so we can deploy. We’ll go through this last part briskly, as we’ve covered most of the important stuff at this point, and pause only briefly to point out what’s important as we go.

Here’s the plan:

We’ll add one more test to make sure the function URL is CORS-friendly
We’ll add another test to make sure the URL resource is bound to the right Lambda function
We’ll add the Lambda code to generate and return the audio file
We’ll deploy, and bask in the warm glow of nostalgia

Let’s get to it.

Add the remaining tests

To index.spec.ts, add two more tests, one to ensure the function is accessible to browsers running on any domain, the other to verify the function URL resource is exposing the right function (if we didn’t, it’d be easy to change that reference by mistake and accidentally expose the wrong function):

describe("My speaking clock", () => {
 // ...

 describe("function URL", () => {
 // ...

 it("is CORS-friendly", async () => {
 const authType = await promiseOf(infra.timeURL.cors);
 expect(authType).toEqual({
 allowOrigins: ["*"],
 allowMethods: ["GET"],
 });
 });

 it("is bound to the right Lambda function", async () => {
 const timeFuncName = await promiseOf(infra.timeFunction.name);
 const timeURLFunc = await promiseOf(infra.timeURL.functionName);
 expect(timeFuncName).toEqual(timeURLFunc);
 });
 });
});

Run the tests, and you should see one failure:

$ npm test

FAIL ./index.spec.ts (14.256 s)
 My speaking clock
 function URL
 ✓ is publicly accessible (3022 ms)
 ✕ is CORS-friendly (3 ms)
 ✓ is bound to the right Lambda function (1 ms)

 Expected: {"allowMethods": ["GET"], "allowOrigins": ["*"]}
 Received: undefined

Tests: 1 failed, 2 passed, 3 total

A quick addition to the FunctionUrl in resources.ts should get you to green:

// ...
export const timeURL = new aws.lambda.FunctionUrl("time-url", {
 functionName: timeFunction.name,
 authorizationType: "NONE",
+ cors: {
+ allowOrigins: ["*"],
+ allowMethods: ["GET"],
+ },
});

$ npm test

PASS ./index.spec.ts
 My speaking clock
 function URL
 ✓ is publicly accessible
 ✓ is CORS-friendly
 ✓ is bound to the right Lambda function

Tests: 3 passed, 3 total

That’s it for the tests! Now for the final additions.

Produce the audio message

The last thing we’ll need to do is render some audio. For this, we’ll need to communicate with Google Translate, our text-to-speech provider of choice, and that means we’ll need an HTTP client. I generally like node-fetch, so let’s go with that:

npm install --save node-fetch@2

Now, finish the program by importing node-fetch into resources.ts, adding a function to produce a speech-friendly string indicating the current time and updating the CallbackFunction’s callback property to send the string to Google Translate to produce the desired result. Here’s the complete file, with comments, for reference:

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

const fetch = require("node-fetch");

// Convert the current time into a speech-friendly string.
export function getSpeechText() {
 const now = new Date();
 now.setSeconds(now.getSeconds() + 6);

 const local = new Date(now.toLocaleString("en-US", { timeZone: "America/Los_Angeles" }));
 const localHour = local.getHours();
 const localMinute = local.getMinutes();
 const h = localHour > 12 ? localHour - 12 : localHour;
 const m = localMinute < 10 ? `oh ${localMinute}` : localMinute; // So 2:03 -> "two-oh-three"
 const s = local.getSeconds();

 return `At the tone, the time will be ${h} ${m}. And ${s} seconds.`;
}

export const timeFunction = new aws.lambda.CallbackFunction("time-function", {

 // Update the Lambda callback body to convert the current time into an MP3 file.
 callback: async () => {
 const text = getSpeechText();
 const speechURL = `https://translate.google.com/translate_tts?ie=UTF-8&q=${encodeURIComponent(text)}&textLen=${text.length}&tl=en&client=tw-ob`;
 const beepURL = "https://www.pulumi.com/uploads/beep.mp3";
 const ttsResponse = await fetch(speechURL);
 const beepResponse = await fetch(beepURL);
 const speech = await ttsResponse.arrayBuffer();
 const beep = await beepResponse.arrayBuffer();

 // Tack a beep onto the end of the audio returned from Google Translate, then
 // render the whole thing as a base-64 encoded string.
 const body = Buffer.concat([Buffer.from(speech), Buffer.from(beep)]).toString("base64");

 // Return an appropriately shaped HTTP response.
 return {
 body,
 headers: { "Content-Type": "audio/mpeg" },
 isBase64Encoded: true,
 statusCode: 200,
 };
 },
});

export const timeURL = new aws.lambda.FunctionUrl("time-url", {
 functionName: timeFunction.name,
 authorizationType: "NONE",
 cors: {
 allowOrigins: ["*"],
 allowMethods: ["GET"],
 },
});

// Export the public URL of our shiny new service.
export const audioURL = timeURL.functionUrl;

Finally, open index.ts (which should still be empty) and add a couple of lines to import the resources module and export the function URL as a Pulumi stack output:

import "./resources";

export { audioURL } from "./resources";

And that’s it. We’re ready to deploy.

Deploy the service

Doublecheck your AWS credentials are configured, then deploy the new service with a single pulumi up:

$ pulumi up

...
Updating (dev)

View Live: https://app.pulumi.com/cnunciato/audichron-2022/dev/updates/1

 Type Name Status
 + pulumi:pulumi:Stack audichron-2022-dev created
 + ├─ aws:iam:Role time-function created
 + ├─ aws:lambda:Function time-function created
 + ├─ aws:iam:RolePolicyAttachment time-function-7cd09230 created
 + ├─ aws:iam:RolePolicyAttachment time-function-a1de8170 created
 + ├─ aws:iam:RolePolicyAttachment time-function-1b4caae3 created
 + ├─ aws:iam:RolePolicyAttachment time-function-019020e7 created
 + ├─ aws:iam:RolePolicyAttachment time-function-4aaabb8e created
 + ├─ aws:iam:RolePolicyAttachment time-function-74d12784 created
 + ├─ aws:iam:RolePolicyAttachment time-function-e1a3786d created
 + ├─ aws:iam:RolePolicyAttachment time-function-6c156834 created
 + ├─ aws:iam:RolePolicyAttachment time-function-b5aeb6b6 created
 + └─ aws:lambda:FunctionUrl time-url created

Outputs:
 audioURL: "https://52rjmmybwfwcud3nxxhosznpum0cycbw.lambda-url.us-west-2.on.aws/"

Resources:
 + 13 created

Duration: 20s

When the update completes, open the URL in your browser of choice, and you should hear the message you’ve been waiting for — one that might even make Pat Fleet proud:

$ open $(pulumi stack output audioURL)

When you’re ready, you can tear everything down with a pulumi destroy.

Wrapping up

Beyond just having a nifty (and admittedly rather silly) new way to tell time, you should have a much better sense at this point of how you can use Pulumi with Jest to write better, safer infrastructure code.

From here, there’s a bunch more you might think about next: writing more tests to cover the code we just added, exploring some additional flavors of testing in the docs, or having a look at a few examples. You’ll find the full source for this walkthrough up on GitHub as well.

Happy testing!

Multicloud with Kubernetes and Pulumi

Guinevere Saenger — Thu, 09 Jun 2022 11:40:47 -0700

In this article we’ll show you how to use Pulumi Components and the Pulumi Automation API to make golden path decisions which will both support your customers on multiple different clouds, and enable infrastructure teams and frontend service teams to more easily own their respective parts of your codebase.

Let’s say you provide a hosted service for your customers. You would like to offer customizable Kubernetes cluster provisioning, on multiple different clouds, as well as your product service itself.

There’s a lot of configuration fine-tuning and manual repetition that is required when bringing up Kubernetes clusters on different clouds.

This article is a written summary of our KubeCrash live demo, see it below. Please find the repository with the full version of the code here.

Part One: Create a component

A Component Resource is an abstraction on top of other Pulumi packages, often combining a few different providers into something that fits your infrastructure needs precisely.

Prerequisites

In our example, we are using three separate clouds, one of these being a local KinD cluster.

Nodejs
Pulumi CLI
Have the Pulumi Registry documentation handy for some Pulumi providers:
- Pulumi Civo Provider
- Pulumi Linode Provider
- Pulumi Kubernetes Provider
- Pulumi KinD Provider (Kubernetes-in-Docker) Note: As this is a community package, follow installation instructions from the README. This provider only supports Go and Nodejs.

Gather access tokens for Linode and Civo, if using, and set them in the environment or as secrets.

Start by writing the code for each cloud

The below code, when run against pulumi up, will create a single cloud stack with three separate Kubernetes clusters. The Stack output will be the cluster’s name and kubeconfig.

import * as pulumi from "@pulumi/pulumi";
import * as civo from '@pulumi/civo';
import * as linode from "@pulumi/linode";
import * as kind from "@pulumi/kind";


//Civo

// Create a firewall
const fw = new civo.Firewall("guin-fw", {
 region: "nyc1",
 createDefaultRules: true,
});

const civoCluster = new civo.KubernetesCluster("guin-civo-demo", {
 name: "guin-demo",
 region: "nyc1",
 firewallId: fw.id,
 pools: {
 nodeCount: 3,
 size: "g4s.kube.xsmall",
 }
});

export const clusterNameCivo = civoCluster.name
export const kcCivo = civoCluster.kubeconfig

//Linode

const linodeCluster = new linode.LkeCluster("guin-linode-demo", {
 k8sVersion: "1.22",
 label: "guin-demo",
 pools: [{
 count: 2,
 type: "g6-standard-2",
 }],
 region: "us-central",
 tags: ["guin-demo"],
});

export const clusterLabelLinode = linodeCluster.label
export const kcLinode = linodeCluster.kubeconfig

// Kind

const kindCluster = new kind.cluster.Cluster(
 'guin-kind',
 {
 name: pulumi.interpolate`guin-kind`,
 nodes: [
 {
 role: kind.node.RoleType.ControlPlane,
 extraPortMappings: [
 {
 containerPort: args.nodePort,
 hostPort: args.nodePort,
 },
 ],
 },
 {
 role: kind.node.RoleType.Worker,
 },
 ],
 },
)

export const clusterNameKind = kindCluster.name
export const kcKind = kindCluster.kubeconfig

We could stop here, export the kubeconfigs to a file, and start interacting with our clusters via kubectl. But that would require our cluster operators to be deeply familiar with each cloud provider’s Kubernetes implementation. Let’s see if we can do better.

Create a custom component for the Kubernetes cluster

Our goal today is to bring up a “generic” Kubernetes cluster that fits a single use case for multiple clouds. To do so, we create a default implementation as a wrapper around each cloud provider. We implement the following features:

Choice of cloud
Cluster Naming
Kubeconfig Output for later use

The Pulumi SDK allows us to wrap resources into a ComponentResource, which in our Typescript example means we create a new class that extends pulumi.ComponentResource.

export class ShinyCluster extends pulumi.ComponentResource {
 constructor(
 name: string,
 args: {},
 opts: {},
 ) {
 # ...
 }
}

Because we like all things shiny, we’ll call it a ShinyCluster, and pass pkg:index:ShinyCluster as the unique resource name.

We’ll also register the name and kubeconfig for each ShinyCluster as Outputs:

import { Output } from '@pulumi/pulumi'; // add this to dependencies

#...

export class ShinyCluster extends pulumi.ComponentResource {
 constructor(
 name: string,
 args: {},
 opts: {},
 ) {
 super('pkg:index:ShinyCluster', name, {}, opts);
 }
 name: Output<string>;
 kubeConfig: Output<string>;
}

Write the implementation for each cloud provider:

export class ShinyCluster extends pulumi.ComponentResource {
 constructor(
 name: string,
 args: {
 cloud: 'linode' | 'civo' | 'kind';
 nodePort?: number; // this is a KinD-specific add-on so we can connect to our workload
 },
 opts: {},
 ) {
 super('pkg:index:ShinyCluster', name, {}, opts);
 switch (args.cloud) {
 case 'linode':
 const linodeCluster = new linode.LkeCluster(
 'my-cluster',
 {
 label: 'guin-linode',
 k8sVersion: '1.22',
 pools: [
 {
 count: 2,
 type: 'g6-standard-2',
 },
 ],
 region: 'us-central',
 tags: ['guin'],
 },
 { parent: this },
 );
 this.name = linodeCluster.label;
 this.kubeConfig = linodeCluster.kubeconfig.apply((x) =>
 Buffer.from(x, 'base64').toString(),
 );
 break;
 case 'civo':
 const fw = new civo.Firewall(
 'guin-fw',
 {
 name: 'guin-civo',
 region: 'nyc1',
 createDefaultRules: true,
 },
 { parent: this },
 );

 const civoCluster = new civo.KubernetesCluster(
 'guin-civo',
 {
 region: 'nyc1',
 name: 'guin-civo',
 firewallId: fw.id,
 pools: {
 nodeCount: 3,
 size: 'g4s.kube.xsmall',
 },
 },
 { parent: this },
 );
 this.name = civoCluster.name;
 this.kubeConfig = civoCluster.kubeconfig;
 break;
 case 'kind':
 const kindCluster = new kind.cluster.Cluster(
 'guin-kind',
 {
 name: 'guin-kind',
 nodes: [
 {
 role: kind.node.RoleType.ControlPlane,
 extraPortMappings: [
 {
 containerPort: args.nodePort,
 hostPort: args.nodePort,
 },
 ],
 },
 {
 role: kind.node.RoleType.Worker,
 },
 ],
 },
 { parent: this },
 );
 this.name = kindCluster.name;
 this.kubeConfig = kindCluster.kubeconfig;
 }
 }
 name: Output<string>;
 kubeConfig: Output<string>;
}

We are now ready to use our component.

Read in the configuration from the config file and create a cluster:

const config = new pulumi.Config();

const shinyCluster = new ShinyCluster(
 'guin',
 {
 cloud: config.require('cloud'),
 nodePort: config.getNumber('nodePort'),
 },
 {},
);

export const shinyName = shinyCluster.name;
export const shinyConfig = pulumi.secret(shinyCluster.kubeConfig);

In our terminal, we can now create a stack called dev, set the necessary inputs in the Pulumi config, and run pulumi up:

$ pulumi stack init dev
Created stack 'dev'
$ pulumi config set shinycluster:cloud civo
$ pulumi up
Previewing update (dev)

View Live: https://app.pulumi.com/guinevere/shinycluster/dev/previews/cf968a89-dadc-461f-badd-b062601c18b4

 Type Name Plan
 + pulumi:pulumi:Stack shinycluster-dev create

At this point, we have created a Pulumi Component Resource that we can use to scaffold Kubernetes infrastructure.

Side Quest: Ship an app!

The purpose of this demo is not focused on the details of deploying a web app on Kubernetes with Pulumi, so we won’t go into too much detail here. We created a shinyapp folder to hold a Pulumi program (written in yaml!) We could now follow the Kubernetes provider configuration steps to set up and deploy our shinyapp to each of our clusters.

But if we have multiple Kubernetes backends, and would like to deploy our shinyapp to each of them, this would get tedious soon. Here is where we automate deploying our frontend as well.

Part 2: Leverage the Automation API

The Pulumi Automation API allows us to run Pulumi commands without using the CLI manually.

Let’s review our basic project file structure first, for context. We place both our shinycluster backend and shinyapp frontend Pulumi projects in their own folders, to separate concerns, and for visual clarity.

.
├── shinyapp
│ ├── Main.yaml # our web app, declared in yaml
│ └── Pulumi.yaml # Pulumi project config for `shinyapp`, with yaml runtime
├── shinycluster
│ ├── index.ts # our showcased Pulumi Component Resource for a Kubernetes cluster
│ └── Pulumi.yaml # Pulumi project config for `shinycluster`, with nodejs (Typescript) runtime

The neat thing here is that both our Kubernetes clusters and our application service are in their own contained folder, and in fact each can be deployed independently using Pulumi. Let’s go ahead and implement the functionality that allows us to automate it all by adding the following files to the root of the project:

├── Pulumi.yaml # Pulumi project config for the entire demo
├── index.ts # Input and output logic for our frontend and backend stacks
├── outputFormatter.ts # Prettify output
├── runPulumiProject.ts # Our specific automation implementation, using Automation API
└── stackModule.ts # Wrapper logic to show which types are expected by each part of our project

Not shown: dependency and package files.

The Stack Module

First, we define a generic Pulumi stack, with variable working directories and outputs, as expected by the automation API.

// stackModule.ts
import * as pulumi from '@pulumi/pulumi';

export type Unwrapped<T> = NonNullable<pulumi.Unwrap<Awaited<T>>>;

export type OutputMap<T> = {
 [K in keyof T]: {
 value: T[K];
 secret: boolean;
 };
};

export type StackModule<T> = {
 workDir: string;
 projectName: string;
 stack(): Promise<T>;
};

type StackOutputs<T> = T extends StackModule<infer O> ? O : never;

/**
 * The type of the outputs, as returned by the automation API as an "OutputMap".
 */
export type StackOutputMap<T> = OutputMap<Unwrapped<StackOutputs<T>>>;

/**
 * The type of the outputs, as if executed and run in a Pulumi program:
 */
export type StackOutputValues<T> = Unwrapped<StackOutputs<T>>;

/**
 * The type of a function that gets values by name from the outputs of a stack.
 *
 * See `stackOutputConfig`.
 */
export type StackOutputGetter<T> = <
 K extends keyof StackOutputValues<T> & string,
>(
 key: K,
) => StackOutputValues<T>[K];

Wrap the Automation API

We have a few functionalities that we can expand on and implement in just the way we like, so we put them in a file called runPulumiProject.ts.

// runPulumiProject.ts
import {
 ConfigMap,
 LocalProgramArgs,
 LocalWorkspace,
 OpMap,
 PreviewResult,
 Stack,
 UpResult
} from '@pulumi/pulumi/automation';

For the purposes of this demo repo, we added a formatter as well, but it’s not necessary for the functionality:

import chalk from 'chalk';
import { Formatter } from './outputFormatter';

And we import the output mappings we abstracted away in the stack module, above.

import { OutputMap, Unwrapped } from './stackModule';

We can now decide how we want to implement our automation options.

Let’s define the options we’d like this program to be able to run with. We need:

Directory name
Project name
Stack name
Pulumi operation to run
Extra configuration (so we can pass in that kubeconfig)
The formatter
Stack outputs

// runPulumiProject.ts
interface PulumiRunOptions {
 dir: string;
 project: string;
 stackName: string;
 operation: 'up' | 'preview' | 'destroy';
 additionalConfig: ConfigMap;
 formatter: Formatter;
}
interface PulumiRunResult<T> {
 stack: Stack;
 projectName: string;
 outputs: OutputMap<Unwrapped<T>>;
}

In this example, the pulumi commands we automate are:

Preview
Up
Destroy

export async function runPulumiProject<T extends object>({
 dir, project, stackName, operation, additionalConfig, formatter,
}: PulumiRunOptions): Promise<PulumiRunResult<T> | undefined> {
 const localProgramArgs: LocalProgramArgs = {
 stackName,
 workDir: dir,
 };
 const stack = await LocalWorkspace.createOrSelectStack(localProgramArgs, {});

 formatter(`Spinning up stack ${project}/${stackName}`);
 await stack.setAllConfig({
 ...additionalConfig,
 });

 formatter('Refreshing');
 await stack.refresh();

 let result: UpResult | PreviewResult;
 let status: string = 'succeeded';
 let outputs: OutputMap<Unwrapped<T>>;
 let summaryMessage: string | undefined;
 let operations: OpMap;
 switch (operation) {
 case 'preview':
 formatter('Previewing');

 const previewResult = await stack.preview({ onOutput: formatter });
 operations = previewResult.changeSummary;
 outputs = (await stack.outputs()) as OutputMap<Unwrapped<T>>;
 break;
 case 'up':
 formatter('Deploying');

 const upResult = await stack.up({ onOutput: formatter });
 operations = upResult.summary.resourceChanges;
 status = upResult.summary.result;
 summaryMessage = upResult.summary.message;
 outputs = upResult.outputs as OutputMap<Unwrapped<T>>;
 break;
 case 'destroy':
 formatter('Destroying');

 const destroyResult = await stack.destroy({ onOutput: formatter });
 operations = destroyResult.summary.resourceChanges;
 status = destroyResult.summary.result;
 summaryMessage = destroyResult.summary.message;
 break;
 }

 if (status !== 'succeeded') {
 formatter(result.stderr);
 formatter(summaryMessage);
 throw new Error();
 }

 if (operations) {
 formatter('Succeeded! Resource summary:');
 const fmtNum = (num?: number) => `${num}`.padStart(3);
 if (operations?.create) {
 formatter(`${fmtNum(operations?.create)} ${chalk.green('created')}`);
 }
 if (operations?.replace) {
 formatter(`${fmtNum(operations?.replace)} ${chalk.magenta('replaced')}`);
 }
 if (operations?.update) {
 formatter(`${fmtNum(operations?.update)} ${chalk.yellow('updated')}`);
 }
 if (operations?.same) {
 formatter(`${fmtNum(operations?.same)} ${chalk.bold('unchanged')}`);
 }
 }

 return {
 stack,
 projectName: project,
 outputs: outputs as OutputMap<Unwrapped<T>>,
 };
}

In addition, this code gives us the ability to take a stack’s Output and apply it to another stack, which is what we will do next, in our top-level index.js file.

Putting it all together

// index.js
import { chooseColor, outputFormatter } from './outputFormatter';
import { runPulumiProject } from './runPulumiProject';

interface ClusterOutputs {
 shinyName: string;
 shinyConfig: string;
}

ClusterOutputs defines the information we need to pass on the kubeconfig to our Kubernetes web app, and the cluster name to associate each frontend stack with its backend Kubernetes cluster.

Here, we’re deploying our shinyapp to a local KinD cluster, but we have the ability to add any cluster to this list:

const clusters = [
 {name: 'kind-local', cloud: 'kind', nodePort: 32001},
];

First, we wait for our clusters to be created (note the operation: 'up' being passed):

await Promise.allSettled(
 clusters.map(async (clusterDefinition) => {
 let theme = chooseColor();

 const serviceType = clusterDefinition.nodePort ? 'NodePort' : 'LoadBalancer';
 const serviceNodePort = `${clusterDefinition.nodePort ?? 0}`;
 const cluster = await runPulumiProject<ClusterOutputs>({
 dir: './shinycluster',
 project: 'shinycluster',
 stackName: clusterDefinition.name,
 operation: 'up',
 additionalConfig: {
 cloud: { value: clusterDefinition.cloud },
 nodePort: { value: serviceNodePort },
 },
 formatter: outputFormatter(`cluster ${clusterDefinition.name}`, theme)
 });
 // here we will call runPulumiProject, this time on the web app
 }),
 );

And then deploy our web app:

runPulumiProject({
 dir: './shinyapp',
 project: 'shinyapp',
 stackName: clusterDefinition.name,
 operation: 'up',
 additionalConfig: {
 kubeconfig: cluster.outputs.shinyConfig,
 serviceType: { value: serviceType },
 serviceNodePort: { value: serviceNodePort },
 },
 formatter: outputFormatter(`app ${clusterDefinition.name}`, theme)
});

Putting it all together:

// index.js
import { chooseColor, outputFormatter } from './outputFormatter';
import { runPulumiProject } from './runPulumiProject';

interface ClusterOutputs {
 shinyName: string;
 shinyConfig: string;
}

async function main() {
 const clusters = [
 { name: 'kind-local', cloud: 'kind', nodePort: 32001 },
 ];

 await Promise.allSettled(
 clusters.map(async (clusterDefinition) => {
 let theme = chooseColor();

 const serviceType = clusterDefinition.nodePort ? 'NodePort' : 'LoadBalancer';
 const serviceNodePort = `${clusterDefinition.nodePort ?? 0}`;
 const cluster = await runPulumiProject<ClusterOutputs>({
 dir: './shinycluster',
 project: 'shinycluster',
 stackName: clusterDefinition.name,
 operation: 'up',
 additionalConfig: {
 cloud: { value: clusterDefinition.cloud },
 nodePort: { value: serviceNodePort },
 },
 formatter: outputFormatter(`cluster ${clusterDefinition.name}`, theme)
 });

 runPulumiProject({
 dir: './shinyapp',
 project: 'shinyapp',
 stackName: clusterDefinition.name,
 operation: 'up',
 additionalConfig: {
 kubeconfig: cluster.outputs.shinyConfig,
 serviceType: { value: serviceType },
 serviceNodePort: { value: serviceNodePort },
 },
 formatter: outputFormatter(`app ${clusterDefinition.name}`, theme)
 });
 }),
 );
}

main();

Run the program

All that is left to do is run our top-level program:

$ ts-node ./index.js

Once that’s done running, go visit your webapp appear on localhost with the specified port:

$ curl localhost:32002
<!DOCTYPE html>
<html>

<head>
 <meta http-equiv="Content-Type" content="text/html" charset="utf-8">
</head>

<body>
 <h1>Made with love by Pulumi!</h1>
</body>

</html>

Summary

We chose some cloud providers for bringing up Kubernetes clusters
We created a ShinyCluster custom resource that abstracts away any cloud provider implementation details, giving us a small set of defaults we care about
We programmatically deployed infrastructure using the Automation API
We deployed an app to this infrastructure, also using Automation API.

We hope you have gotten a little bit of inspiration from our whirlwind tour through these Pulumi features. Happy coding!

Deploy MERN Stack on DigitalOcean with Pulumi [Guide]

Christian Nunciato — Fri, 11 Mar 2022 00:00:00 +0000

As a developer, I get lots of ideas for web apps—little things, mostly: nifty ways to keep track of my kids’ allowances, habit trackers, shopping lists. Most of them, however, never see the light of day, and not just because I’m lazy; I also tend to get hung up trying to decide what to use for the technology stack.

And as a JavaScript developer, I certainly have options—too many, in fact, and that’s part of the problem. Having roughly a hundred and fifty million libraries and frameworks to choose from is definitely better than having none, but at the same time, all that choice can make the actual choosing rather difficult. Which is why, when I just want to get something done, I’ll often reach for a combination of tools known as the MERN stack.

MERN-stack apps are three-tier web apps built with MongoDB, Express, React, and Node.js. You can read all about them in the MongoDB docs, but the gist is that they allow you use one language—JavaScript (or TypeScript, if you like)—to manage all three layers of the application stack: the front end as a single-page app built statically with React, the back end as a REST API managed with Express, and the database as a collection of JSON-like documents with MongoDB. MERN might not always the right tool for the job, but for the kinds of apps I tend to find myself building, it generally works out pretty well.

Still, once I’m finished building my app, I’m often faced with a whole other problem: figuring out how to get the app off of my laptop and onto the web.

The cloud hasn’t made this an easy task for developers. Choosing a cloud provider, deciding which resources to use (and how to use them), setting up networking, debugging permissions, navigating billing, and all the rest, can be overwhelming—and that’s before you’ve given a single thought to anything having to do with automation or infrastructure as code. What we want, I think, is to be able to focus on our apps, and when we’re ready to ship, push our code to a repository and wait patiently for a URL to emerge that we can paste into a browser and have everything just work.

Which is why I was so delighted when I discovered DigitalOcean’s App Platform.

If you’ve used DigitalOcean before, you know it’s all about making infrastructure more accessible to developers. What you may not know, though, or at least I didn’t myself until recently, is that you can do a lot more with DigitalOcean than just virtual machines. A fairly new, fully-managed platform service (think Heroku), App Platform gives you a set of high-level abstractions built to align with the tiers of a typical web application, which means you can focus on what you care about most—your app—and leave the infrastructure and its management to someone else. It’s a compelling option for anyone looking to deploy and manage any web application (MERN or otherwise), and as you’ll see, with Pulumi and a little bit of code, you can easily do so without ever having to leave the comfort of your IDE.

So let’s build ourselves a MERN app and deploy it on DigitalOcean with Pulumi. Given the goal is to focus primarily on the infrastructure and how to code it, we’ll start with a pre-baked web application (a simple grocery list), and we’ll map its tiers to App Platform constructs and wire everything up with Pulumi.

First steps: setting up

The code for this walkthrough is available as a template repository on GitHub, so if you want to follow along (and you should!), you should grab a copy of your own to work with by forking the repository or creating a new one from the template. Once you’ve done that, you should also:

Clone the repository to your local machine.
Install Pulumi and Node.js.
Sign into DigitalOcean and obtain a personal access token with read-write permissions.
Grant DigitalOcean access to your GitHub repository by visiting the Apps page, choosing Create App, and following the steps to install DigitalOcean’s GitHub app.
Optionally, if you’d like to develop the application locally as well, install and configure MongoDB Community Edition.

One thing to note: Since we’ll be provisioning real DigitalOcean resources, there’s a chance you could incur a slight cost for what you use. However, as we’ll be using the least expensive plan settings available, and tearing everything down when we’re through, that cost shouldn’t amount to more than a few pennies or so.

Let’s get started.

Cloning and inspecting the repository

Once you’ve cloned your copy of the template repository and navigated to the root, you’ll see a couple of files and folders that look something like this:

├── frontend
├── backend
└── package.json

The frontend folder contains the React application, and its job is to render the list of groceries and give you something to interact with (to add items, check them off, delete them, and so on). The scaffolding for the app was generated with a tool called Vite, and all of its logic—form fields, click handlers, API calls, etc.—is contained in src/App.tsx.

The backend folder contains the Express application that defines the REST API. It sets up four API routes to handle the CRUD operations you’d expect in an app like this one:

GET /api/items fetches all items from the database and returns them as a JSON array.
POST /api/items accepts a new item and writes it to the database.
PUT /api/items/:id updates an existing item (to toggle its checked/unchecked status).
DELETE /api/items/:id deletes an item from the database.

The back end supports three configurable properties as well, all of which are exposed as optional environment variables:

BACKEND_SERVICE_PORT, which defaults to 8000
BACKEND_ROUTE_PREFIX, which defaults to /api
DATABASE_URL, which defaults to mongodb://127.0.0.1 for local development

Running the application locally (optional)

You don’t have to do this, but if you’d like to, here’s how. After installing MongoDB and starting the service (which should be listening by default on port 27107), you can install all front-end and back-end dependencies and start the development server:

$ npm install
$ npm start

With the development server running, you can browse to http://localhost:3000 and see the app:

The front-end and back-end dev servers are set up to compile your TypeScript to JavaScript automatically, and the front-end server is configured to proxy the back-end service (which runs at http://localhost:8000) at a root-relative path of /api. Proxying the API in this way lets you avoid having to wrestle with CORS-related issues, and as you’ll see when we deploy to DigitalOcean later, App Platform conveniently supports the same configuration out of the box.

Try adding a few items and marking them off, just to make sure everything’s working as expected. If you’ve got a MongoDB client installed as well—I generally use MongoDB Compass—you should be able to find the grocery-list database and see the items collection filling up with delicious foods:

Now let’s have a look at how to go about deploying this stuff.

Charting a course

Earlier I mentioned that every cloud provider handles application deployment a little differently, sometimes in multiple ways, and that’s true for DigitalOcean as well. You could deploy the front end as a DigitalOcean Space, or both the front end and back end (and even the database) as a DigitalOcean Droplet. But given the shape of this application, the best fit is really is App Platform, for several reasons.

One is that because App Platform apps are comprised of these high-level components—abstractions like static site, service, and database—it’s pretty much purpose-built for an application like this one, and DigitalOcean customizes the deployment of each component based on its type. Static websites are distributed and cached on DigitalOcean’s CDN, services are packaged and delivered as containers (with its Kubernetes platform), and databases are deployed as configurable managed services. All of this means you’re not only able to stay focused on the application itself, but you’re able to scale each one of these components up or down however you like, and even delegate your front-end and back-end build processes to DigitalOcean to be handled in response to commits on one or more external Git repositories.

App Platform apps can be configured in one of two ways: manually, by configuring their components individually in the DigitalOcean web console, or programmatically, in the form of an App Platform spec, a JSON document submitted over DigitalOcean’s REST API. In our case, we’ll indirectly go the latter route, using Pulumi with the DigitalOcean provider package to define an app spec comprised of three components:

A staticSite component mapped to the frontend folder
A service component mapped to the backend folder
A database component mapped to a managed MongoDB cluster (which we’ll also configure to be accessible only by the service component)

And once deployed, it’ll all be available at a single DigitalOcean-provided URL.

Let’s begin by creating new Pulumi project.

Creating the project

In the root of the repository, make a new folder called infra, change to it, then run pulumi new using the digitalocean project template:

$ mkdir infra && cd infra
$ pulumi new digitalocean-typescript

$ mkdir infra && cd infra
$ pulumi new digitalocean-python

At the prompts, use the following values:

For project name, use grocery-list
For description, use Deploying a MERN-stack app on DigitalOcean
For stack name, use dev, the default

When the command completes, you’ll have a new Pulumi stack, but you’ll still have a few things to configure. For one, the Pulumi DigitalOcean provider needs to be configured to communicate with DigitalOcean on your behalf (to provision your app and its various resources). For this, you can use the access token you obtained earlier from the DigitalOcean console, and you can apply it by setting a single environment variable:

$ export DIGITALOCEAN_TOKEN="your-access-token"

Also, since one of our goals is to have App Platform deploy automatically on every GitHub commit, you’ll need to tell DigitalOcean where to find the source code for your front- and back-end components. You could bake these settings right into the Pulumi program itself, but it’d be better to apply them as stack-specific configuration settings, as that’d let you deploy to different stacks later (say, in CI) based on the branch of the commit. Everyone does this a little differently, so for now, let’s configure the currently selected stack (which should be dev) to use the default branch of your GitHub repository:

$ pulumi config set repo "your-github-org/your-github-repo" # e.g., cnunciato/fullstack-pulumi-mern-digitalocean
$ pulumi config set branch "your-main-branch" # e.g., main

With these values in place, you’re ready to start writing the program.

App Platform also supports GitLab and other Git-based repositories as well. See the App Specification docs for details.

Writing the program

In your IDE of choice, open index.js index.ts main.py main.go Program.cs Program.fs Program.vb App.java Pulumi.yaml main.tf and replace the sample code with the following lines to import the Pulumi and DigitalOcean SDKs and the configuration values you just set, and add a line to specify the DigitalOcean region to deploy into:

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

// Our stack-specific configuration.
const config = new pulumi.Config();
const repo = config.require("repo");
const branch = config.require("branch");

// The DigitalOcean region to deploy into.
const region = digitalocean.Region.SFO3;

import pulumi
import pulumi_digitalocean as digitalocean

# Our stack-specific configuration.
config = pulumi.Config()
repo = config.require("repo")
branch = config.require("branch")

# The DigitalOcean region to deploy into.
region = digitalocean.Region.SFO3

Next, add a few lines to declare the managed MongoDB cluster. We’ll use just one node for now—additional replica nodes can easily be added later by increasing the nodeCount value—and go with the least expensive performance settings:

// ...

// Our MongoDB cluster (currently just one node).
const cluster = new digitalocean.DatabaseCluster("cluster", {
 engine: "mongodb",
 version: "5",
 region,
 size: digitalocean.DatabaseSlug.DB_1VPCU1GB,
 nodeCount: 1,
});

// The database we'll use for our grocery list.
const db = new digitalocean.DatabaseDb("db", {
 name: "grocery-list",
 clusterId: cluster.id,
});

# ...

# Our MongoDB cluster (currently just one node).
cluster = digitalocean.DatabaseCluster("cluster", digitalocean.DatabaseClusterArgs(
 engine = "mongodb",
 version = "5",
 region = region,
 size = digitalocean.DatabaseSlug.D_B_1_VPCU1_GB,
 node_count = 1
))

# The database we'll use for our grocery list.
db = digitalocean.DatabaseDb("db", digitalocean.DatabaseDbArgs(
 name = "grocery-list",
 cluster_id = cluster.id
))

Now for the App Platform spec itself. Notice the digitalocean.App resource takes just one argument, spec, which defines all three of the components of the app: static site, service, and database. Both the static site and the service are configured to use the same GitHub repository (the sourceDir properties indicate their folders within the repository), and both are configured (via the deployOnPush flag) to be rebuilt and redeployed by DigitalOcean on every commit.

The service has a few additional settings that you can use to manage its runtime behavior and deployment topology as well. As in development, we’ll configure the service to listen on port 8000 and be available at /api—the entire app will ultimately be proxied transparently by an App Platform load balancer—and it’ll be powered by just one container instance, again using the least expensive performance settings:

// ...

// The App Platform spec that defines our grocery list.
const app = new digitalocean.App("app", {
 spec: {
 name: "grocery-list",
 region: region,

 // The React front end.
 staticSites: [
 {
 name: "frontend",
 github: {
 repo,
 branch,
 deployOnPush: true,
 },
 sourceDir: "/frontend",
 buildCommand: "npm install && npm run build",
 outputDir: "/dist",
 }
 ],

 // The Express back end.
 services: [
 {
 name: "backend",
 github: {
 repo,
 branch,
 deployOnPush: true,
 },
 sourceDir: "/backend",
 buildCommand: "npm install && npm run build",
 runCommand: "npm start",
 httpPort: 8000,
 routes: [
 {
 path: "/api",
 preservePathPrefix: true,
 },
 ],
 instanceSizeSlug: "basic-xxs",
 instanceCount: 1,

 // To connect to MongoDB, the service needs a DATABASE_URL, which
 // is conveniently exposed as an environment variable thanks to its
 // membership in this app spec (below).
 envs: [
 {
 key: "DATABASE_URL",
 scope: "RUN_AND_BUILD_TIME",
 value: "${db.DATABASE_URL}",
 },
 ],
 },
 ],

 // Include the MongoDB cluster as an integrated App Platform component.
 databases: [
 {
 // The name `db` defines the prefix of the tokens used (above) to
 // read the environment variables exposed by the database cluster.
 name: "db",

 // MongoDB clusters are only available in "production" mode.
 // https://docs.digitalocean.com/products/app-platform/how-to/manage-databases/
 production: true,

 // A reference to the `DatabaseCluster` we declared above.
 clusterName: cluster.name,

 // The engine value must be uppercase, so we transform it with JS.
 engine: cluster.engine.apply(engine => engine.toUpperCase()),
 }
 ]
 },
});

# ...

# The App Platform spec that defines our grocery list.
app = digitalocean.App("app", digitalocean.AppArgs(
 spec = digitalocean.AppSpecArgs(
 name = "grocery-list",
 region = region,

 # The React front end.
 static_sites = [
 digitalocean.AppSpecStaticSiteArgs(
 name = "frontend",
 github = digitalocean.AppSpecJobGithubArgs(
 repo = repo,
 branch = branch,
 deploy_on_push = True
 ),
 source_dir = "/frontend",
 build_command = "npm install && npm run build",
 output_dir = "/dist"
 )
 ],

 # The Express back end.
 services = [
 digitalocean.AppSpecServiceArgs(
 name = "backend",
 github = digitalocean.AppSpecJobGithubArgs(
 repo = repo,
 branch = branch,
 deploy_on_push = True
 ),
 source_dir = "/backend",
 build_command = "npm install && npm run build",
 run_command = "npm start",
 http_port = 8000,
 routes = [
 digitalocean.AppSpecServiceRouteArgs(
 path = "/api",
 preserve_path_prefix = True
 )
 ],
 instance_size_slug = "basic-xxs",
 instance_count = 1,

 # To connect to MongoDB, the service needs a DATABASE_URL, which
 # is conveniently exposed as an environment variable because the
 # database belongs to the app (see below).
 envs = [
 digitalocean.AppSpecServiceEnvArgs(
 key = "DATABASE_URL",
 scope = "RUN_AND_BUILD_TIME",
 value = "${db.DATABASE_URL}"
 )
 ]
 )
 ],

 # Include the MongoDB cluster as an integrated App Platform component.
 databases = [
 digitalocean.AppSpecDatabaseArgs(
 # The `db` name defines the prefix of the tokens used (above) to
 # read the environment variables exposed by the database cluster.
 name = "db",

 # MongoDB clusters are only available in "production" mode.
 # https://docs.digitalocean.com/products/app-platform/concepts/database/
 production = True,

 # A reference to the managed cluster we declared above.
 cluster_name = cluster.name,

 # The engine value must be uppercase, so we transform it with Python.
 engine = cluster.engine.apply(lambda engine: engine.upper())
 )
 ]
 ),
))

Technically that’s all we need to configure the application—but it wouldn’t be a bad idea to add one last thing.

By default, managed MongoDB clusters are configured to be publicly accessible—which is great if you need to be able to connect one yourself, but not so great as a strategy for preventing internet miscreants from doing the same. You can fix this easily by adding a DatabaseFirewall resource to declare the app as a trusted source, thereby rejecting all inbound traffic originating from elsewhere:

// ...

// Adding a database firewall setting grants access solely to our app.
const trustedSource = new digitalocean.DatabaseFirewall("trusted-source", {
 clusterId: cluster.id,
 rules: [
 {
 type: "app",
 value: app.id,
 },
 ],
});

# ...

# Adding a database firewall setting restricts access solely to our app.
trusted_source = digitalocean.DatabaseFirewall("trusted-source", digitalocean.DatabaseFirewallArgs(
 cluster_id = cluster.id,
 rules = [
 digitalocean.DatabaseFirewallRuleArgs(
 type = "app",
 value = app.id
 )
 ],
))

And finally, add one last line to export the app URL, to be generated by DigitalOcean, as a Pulumi stack output:

// ...

// The DigitalOcean-assigned URL for our app.
export const { liveUrl } = app;

# ...

# The DigitalOcean-assigned URL for our app.
pulumi.export("liveUrl", app.live_url)

With that, you’re ready to deploy.

Deploying

Quickly, to recap, here’s what we’ve done so far:

We took a pre-baked MERN app configured to run on localhost.
We mapped the tiers of that app to their corresponding App Platform components.
We wrote a Pulumi program to codify that mapping as an App Platform spec and a managed MongoDB cluster to go along with it.

When you deploy this app in a moment with pulumi up, Pulumi will provision a new MongoDB cluster (which usually takes a few minutes), and then once that’s available, DigitalOcean will take our spec and use it to fetch the components of the app from GitHub at the specified branch and build them. From that point forward, any commit you make to that branch will trigger DigitalOcean to fetch, rebuild, and redeploy the app automatically.

Make sure you’ve installed the DigitalOcean GitHub app as described above—you should see it listed at https://github.com/settings/installations:

Now return to the command line and run pulumi up:

$ pulumi up

Previewing update (dev)

View Live: https://app.pulumi.com/cnunciato/grocery-list/dev/previews/605bf32a-95b1-4221-bc35-0e667b30f38a

 Type Name Plan
 + pulumi:pulumi:Stack grocery-list-dev create
 + ├─ digitalocean:index:DatabaseCluster cluster create
 + ├─ digitalocean:index:DatabaseDb db create
 + ├─ digitalocean:index:App app create
 + └─ digitalocean:index:DatabaseFirewall trusted-source create

Resources:
 + 5 to create

Do you want to perform this update?
> yes

Updating (dev)

View Live: https://app.pulumi.com/cnunciato/grocery-list/dev/updates/1

 Type Name Status
 pulumi:pulumi:Stack grocery-list-dev
 + ├─ digitalocean:index:App app created
 + └─ digitalocean:index:DatabaseFirewall trusted-source created

Outputs:
 + liveUrl: "https://grocery-list-fb9bd.ondigitalocean.app"

Resources:
 + 2 created
 3 unchanged

Duration: 2m30s

Again, it’ll probably take a few minutes to get everything spun up for the first time, but when the process completes, you’ll have a working app at the URL provided by DigitalOcean, emitted as a Pulumi stack output:

$ open $(pulumi stack output liveUrl)

$ open $(pulumi stack output live_url)

You should also be able to explore your shiny new grocery-list app in the DigitalOcean Console, with all three of its components (and their build-time and runtime logs!) now represented:

Now try making a commit to your repository (any commit will do, but ideally one to the frontend or backend folder), and watch as the app redeploys automatically:

And finally, try scaling the service by bumping the instanceCount from 1 to 2 in the code—or better, if you’re up for it, making that value configurable by stack:

 const config = new pulumi.Config();
 const repo = config.require("repo");
 const branch = config.require("branch");
+ const serviceInstanceCount = config.requireNumber("service_instance_count");
 ...
 services: [
 digitalocean.AppSpecServiceArgs(
 ...
+ instanceCount: serviceInstanceCount,

 config = pulumi.Config()
 repo = config.require("repo")
 branch = config.require("branch")
+ service_instance_count = config.requireNumber("service_instance_count");
 ...
 services: [
 digitalocean.AppSpecServiceArgs(
 ...
+ instance_count: service_instance_count,

Set the instance count with pulumi config:

$ pulumi config set service_instance_count 2

Then deploy the new app spec with a final pulumi up:

$ pulumi up

Updating (dev)

 Type Name Status Info
 pulumi:pulumi:Stack grocery-list-dev
 ~ └─ digitalocean:index:App app updated [diff: ~spec]

Outputs:
 liveUrl: "https://grocery-list-fb9bd.ondigitalocean.app"

Resources:
 ~ 1 updated
 4 unchanged

Duration: 1m27s

And when you’re finished experimenting, you can tear everything down in just a few seconds with a pulumi destroy:

$ pulumi destroy

Destroying (dev)

 Type Name Status
 - pulumi:pulumi:Stack grocery-list-dev deleted
 - ├─ digitalocean:index:DatabaseFirewall trusted-source deleted
 - ├─ digitalocean:index:DatabaseDb db deleted
 - ├─ digitalocean:index:App app deleted
 - └─ digitalocean:index:DatabaseCluster cluster deleted

Resources:
 - 5 deleted

Duration: 19s

Wrapping up, and next steps

Hopefully this gives you a sense of the kinds of things you can do with Pulumi and DigitalOcean—and I definitely encourage you to spend a little time with the App Platform docs to dig a bit deeper into some of these concepts and explore a few others we weren’t able to cover. You’ll find the full source for this walkthrough on GitHub, of course, with finished branch containing the completed Pulumi program for reference.

From here, you might think about:

Adding a digitalocean.DnsRecord to give your app a custom domain name.
Creating a second stack with pulumi stack init and adjusting the program to make the source branch configurable—a production stack, say, designed to deploy in response to commits to a release branch.
Using Pulumi’s GitHub Action to run previews and updates as part of a pull-request based workflow.

Happy coding!

Create Amazon EKS clusters in your favorite language

Levi Blackstone — Thu, 04 Feb 2021 00:00:00 +0000

Check out version 3.0 of the Pulumi EKS Provider.

Pulumi’s infrastructure as code tooling combines the programming languages and tools you already know with the full power of cloud infrastructure. But until now, some Pulumi components for cloud infrastructure, like our popular EKS package for Amazon’s Elastic Kubernetes Service, were only available in a subset of the languages supported by Pulumi.

Now, you can use the EKS package–previously only available for TypeScript–in all four Pulumi languages: TypeScript, Python, .NET, and Go. Regardless of the language you choose, you can manage EKS clusters with Pulumi, starting with the v0.22.0 release. Check out our Modern Infrastructure Wednesday video to see it in action:

Making components available in every language

Pulumi’s EKS package is made up of Pulumi components. A component is a collection of Pulumi resources that provides an easy way to package best practices for using cloud resources, even if those best pratices span individual resources or even entire cloud providers. Until now though, components could only be used in Pulumi programs written in the same language as the component.

To change that, we’re creating “multi-language components”. With multi-language components, anyone will be able to author a component in one language and automatically compile it to all other languages supported by Pulumi. This means anyone in the worldwide Pulumi community will be able to take advantage of any component, even if it’s written in a different language. Right now, unless a component author is willing to write code in all four Pulumi languages, their component is only able to reach Pulumi users using the same language SDK.

In addition to expanding the library of publicly available components, this work will also enable organizations to write Pulumi components in the right programming language, or languages, for each team and each product. Infrastructure or platform teams will be able to write components in Go and share them with a webapp team using TypeScript, write components in .NET and share them with a machine learning team using Python, and any other combination that suits their business.

The next step in the story is a seamless authoring experience that enables component creators to write, build, and publish multi-language components. That will be in public preview soon, and we’re excited for you to try it out. If you’d like, subscribe to the multi-language components issue for updates.

Next steps

If you haven’t yet, try out the new pulumi-eks package with this walkthrough.

Announcing Cross-Language Enum Support

Komal Ali — Tue, 15 Dec 2020 00:00:00 +0000

Here at Pulumi, we believe in leveraging the best features of programming languages to create a delightful development experience for our users. Today, we continue our contributions in this area by announcing cross-language support for enum types in our provider SDKs, available in all Pulumi languages - Python, TypeScript, .NET and Go.

Enum types explained

An enum (short for enumerated) type is a data type consisting of a set of named values. In the Pulumi resource model, a property is an enum type when its value can only be set to a finite number of predetermined values.

For instance, consider a simple S3 bucket.

import * as pulumi from "@pulumi/pulumi";
import { s3 } from "@pulumi/aws";

const myBucket = new s3.Bucket("myBucket", { acl: "private" });

import pulumi
from pulumi_aws import s3

my_bucket = s3.Bucket("myBucket", acl="private")

using Pulumi;
using S3 = Pulumi.Aws.S3;

class MyStack : Stack
{
 public MyStack()
 {
 var myBucket = new S3.Bucket("myBucket", new S3.BucketArgs
 {
 Acl = "private",
 });
 }
}

package main

import (
 "github.com/pulumi/pulumi-aws/sdk/v3/go/aws/s3"
 "github.com/pulumi/pulumi/sdk/v2/go/pulumi"
)

func main() {
 pulumi.Run(func(ctx *pulumi.Context) error {
 myBucket, err := s3.NewBucket(ctx, "myBucket", &s3.BucketArgs{
 Acl: pulumi.String("private"),
 })
 if err != nil {
 return err
 }
 return nil
 })
}

In the above code, the S3 Bucket resource has a property called acl, where we pass in the string private to indicate that this is a private bucket.

If we look at the resource docs, we can see that the acl property can only be set to one of a few different values: private, public-read, public-read-write, aws-exec-read, authenticated-read, and log-delivery-write. The acl property is the perfect candidate for an enum type and is emitted as one, so you can use the following code instead.

import * as pulumi from "@pulumi/pulumi";
import { s3 } from "@pulumi/aws";

const myBucket = new s3.Bucket("myBucket", { acl: s3.CannedAcl.Private });

import pulumi
from pulumi_aws import s3

my_bucket = s3.Bucket("myBucket", acl=s3.CannedAcl.PRIVATE)

using Pulumi;
using S3 = Pulumi.Aws.S3;

class MyStack : Stack
{
 public MyStack()
 {
 var myBucket = new S3.Bucket("myBucket", new S3.BucketArgs
 {
 Acl = S3.CannedAcl.Private,
 });
 }
}

package main

import (
 "github.com/pulumi/pulumi-aws/sdk/v3/go/aws/s3"
 "github.com/pulumi/pulumi/sdk/v2/go/pulumi"
)

func main() {
 pulumi.Run(func(ctx *pulumi.Context) error {
 myBucket, err := s3.NewBucket(ctx, "myBucket", &s3.BucketArgs{
 Acl: s3.CannedAclPrivate,
 })
 if err != nil {
 return err
 }
 return nil
 })
}

IDE Superpowers

Enum properties provide discoverable and normalized constants that can be used in place of raw strings, allowing you to move faster with the added boosts of IDE tooling like type hints and autocomplete.

Using the provided constants, you can avoid referring back to the documentation to remember the valid values and save precious moments in the development cycle that would be lost to debugging errors caused by typos.

Optimized for flexibility

While some properties make sense as “strict” enums (i.e., the input value must be one of the enumerated values), there are times when it would be beneficial to have constants for commonly used values without restricting the input to only those values. We call this second category “relaxed” enums, and we model them a little differently in our SDKs.

“Strict” enums

A property is a “strict” enum when the input value must be one of the enumerated values. In this case, the property type is specified as the enum type.

We will use “strict” enums when we are sure that the enum will include all legal values, such as when a provider is auto-generated from a cloud provider specification (like our Azure-Native or Kubernetes providers).

export class StorageAccount extends pulumi.CustomResource {
 constructor(name: string, args: StorageAccountArgs, opts?: pulumi.CustomResourceOptions) {...}
}

export interface StorageAccountArgs {
 readonly accessTier?: pulumi.Input<enums.storage.latest.AccessTier>;
 ...
}

class StorageAccount(pulumi.CustomResource):
 def __init__(__self__,
 resource_name: str,
 access_tier: Optional[pulumi.Input['AccessTier']] = None,
 ...):
 ...

namespace Pulumi.AzureNative.Storage
{
 public partial class StorageAccount : Pulumi.CustomResource
 {
 public StorageAccount(string name, StorageAccountArgs args, ...)
 {
 }
 }

 public sealed class StorageAccountArgs : Pulumi.ResourceArgs
 {
 [Input("accessTier")]
 public Input<Pulumi.AzureNative.Storage.AccessTier>? AccessTier { get; set; }

 ...
 }
}

func NewStorageAccount(ctx *pulumi.Context,
name string, args *StorageAccountArgs, ...) (*StorageAccount, error) {
 ...
}

type StorageAccountArgs struct {
 AccessTier AccessTier
 ...
}

When using TypeScript, “strict” enums will accept both the constant (AccessTier.Cool) or the literal string ("Cool"). If there is an accidental spelling error in the literal, you are immediately alerted to the issue rather than having to wait until runtime.

“Relaxed” enums

When a property is a “relaxed” enum, the property type is specified as the Union of the enum type and the underlying primitive type. This means that you have the convenience of using the enum constants (i.e., s3.CannedAcl.Private), but you may also pass in the raw string (i.e., "private").

In the AWS provider (and other Terraform-based providers), we have opted for only using “relaxed” enums. The reasoning is twofold. Allowing the primitive type maintains backward compatibility and also allows users to use values that may not yet be represented in the Pulumi schema (e.g., a new Managed Policy ARN, EC2 Instance type, etc.).

export class Bucket extends pulumi.CustomResource {
 constructor(name: string, args?: BucketArgs, opts?: pulumi.CustomResourceOptions) {...}
}

export interface BucketArgs {
 readonly acl?: pulumi.Input<string | enums.s3.CannedAcl>;
 ...
}

class Bucket(pulumi.CustomResource):
 def __init__(__self__,
 resource_name: str,
 acl: Optional[pulumi.Input[Union[str, 'CannedAcl']]] = None,
 ...):
 ...

namespace Pulumi.Aws.S3
{
 public partial class Bucket : Pulumi.CustomResource
 {
 public Bucket(string name, BucketArgs? args = null, ...)
 {
 }
 }

 public sealed class BucketArgs : Pulumi.ResourceArgs
 {
 [Input("acl")]
 public InputUnion<string, Pulumi.Aws.S3.CannedAcl>? Acl { get; set; }

 ...
 }
}

func NewBucket(ctx *pulumi.Context,
name string, args *BucketArgs, ...) (*Bucket, error) {
 ...
}

// In Go, relaxed enums retain the type of the underlying primitive.
// However, the CannedAcl constants may still be passed in, as they are
// of the same underlying type.
type BucketArgs struct {
 Acl pulumi.StringPtrInput
 ...
}

Try them out!

You can find enum types integrated into v3.19.0 of the AWS provider and v0.7.1 of the Azure-Native provider, and we will be adding enums to other providers in the coming weeks and months.

Azure-Native: In the native Azure provider, all properties labeled as enums in the OpenAPI spec are represented as such. In all, there are over 1300 enums provided in the SDKs. The native Azure provider uses both “strict” and “relaxed” enums since the OpenAPI specification explicitly defines its properties as such.

AWS: The AWS provider enums are manually identified and maintained as part of the provider schema. We’ve already added many that you might find useful, such as Lambda Runtimes, EC2 Instance Types, and IAM Managed Policies, and will continue to add more in the coming months.

Take the new providers for a spin and let us know what you think in the Community Slack! If there are properties that you would like to see represented as enums, let us know. Or even better, submit a PR like this one to add them to the schema!

Switching the application stack from PERN to MERN

Vova Ivanov — Fri, 18 Sep 2020 00:00:00 +0000

This post is outdated and contains references to a pre-release version of Pulumi Crosswalk (@pulumi/awsx). For updated AWSx documentation and examples, see the AWS Guides.

In this blog post, we return to the PERN application we previously migrated to Kubernetes and replace the PostgreSQL database with MongoDB. Although it might seem like a difficult task initially, the straightforward design of Pulumi and Kubernetes allows us to easily transition the application form a PERN stack to a MERN one.

The main difference between PostgreSQL and MongoDB is data is stored. PostgreSQL is a relational database that allows users to create complex tables and relations between values. In contrast, MongoDB is a key-value database that stores data in simple collections instead of a relational model. Because the application takes the form of three distinct components–the client, server, and database–almost all of the changes will occur in the database component. In fact, we can reuse most of the existing code and will be able to change the database without additional hassle.

The first step to switching the stack is to clone the PERN Kubernetes example. We’ll use a sparse clone to copy only the aws-ts-k8s-voting-app directory.

$ mkdir examples && cd examples
$ git init
$ git remote add origin -f https://github.com/pulumi/examples/
$ git config core.sparseCheckout true
$ echo aws-ts-k8s-voting-app >> .git/info/sparse-checkout
$ git pull origin master

The next step is to create a new directory and initialize a Pulumi project with pulumi new aws-typescript.

$ mkdir aws-ts-k8s-mern-voting-app && cd aws-ts-k8s-mern-voting-app
$ pulumi new aws-typescript

The project will require several configuration variables, which we set using pulumi config set. The variables are used to configure the MongoDB user account, initializing the database schema and table, and its region.

$ pulumi config set sql-user-name <NAME>
$ pulumi config set sql-user-password <PASSWORD> --secret
$ pulumi config set aws:region <REGION>

The package.json file lists the libraries used by the project. We will add the following to the dependencies section:

 "@pulumi/eks": "^0.20.0",
 "@pulumi/cloud-aws": "^0.19.0"

As most of our project components are nearly identical to those in the PERN Kubernetes application, we can copy many of them into our directory.

$ cd ..
$ cp -r aws-ts-k8s-voting-app/clientside/ aws-ts-k8s-mern-voting-app/clientside
$ cp -r aws-ts-k8s-voting-app/serverside/ aws-ts-k8s-mern-voting-app/serverside
$ cp -r aws-ts-k8s-voting-app/databaseside/ aws-ts-k8s-mern-voting-app/databaseside

$ cd aws-ts-k8s-voting-app

Hosting MongoDB will require a rework of the database Docker container and startup scripts. Like before, the outer databaseside folder holds our Dockerfile, while the inner database folder contains code.

FROM ubuntu:18.04

WORKDIR /

EXPOSE 5432

RUN apt update && \
 apt install -y mongodb

ADD database /database

CMD [ "/database/startDatabase.sh" ]

Our setup doesn’t require any files, and so the only thing we need to put in the database folder is a startDatabase.sh script that launches the database, configures users, and creates a table.

#!/bin/bash
set -exu
FILE=/persistentVolume/mongod.lock

if test -f "$FILE"; then
 echo "/persistentVolume already contains MongoDB, no need to initialize database."
 mongod --fork --dbpath /persistentVolume/ --bind_ip_all --logpath /persistentVolume/mongoLogs
else
 echo "/persistentVolume is empty, and we need to initialize the MongoDB database."
 mongod --fork --dbpath /persistentVolume/ --bind_ip_all --logpath /persistentVolume/mongoLogs
 echo "use $DATABASE_NAME
 db.choices.insert({ _id: 0, text: \"Tabs\", vote_count: 0 })
 db.choices.insert({ _id: 1, text: \"Spaces\", vote_count: 0 })
 db.createUser(
 {
 user: \"$USER_NAME\",
 pwd: \"$USER_PASSWORD\",
 roles: [ { role: \"readWrite\", db: \"$DATABASE_NAME\" } ]
 }
 )" | mongo
fi

while true; do
 sleep 3600
done

With the database in place, all that is left is to make some small MongoDB-specific changes to how the client and server components send queries.

The server component will be changed to use a model.js file, which acts as a blueprint for the database’s choices.

const mongoose = require("mongoose");

let Choice = new mongoose.Schema({
 _id: Number,
 text: {
 type: String
 },
 vote_count: {
 type: Number
 },
});

module.exports = mongoose.model("choice", Choice);

Likewise, the db.js file will be modified to create a specialized to our database.

const mongoose = require("mongoose");

const url = "mongodb://"
 + process.env["MONGODB_ADDRESS"]
 + ":" + process.env["MONGODB_PORT"]
 + "/" + process.env["DATABASE_NAME"]

mongoose.connect(url, {
 useNewUrlParser: true,
 user: process.env["USER_NAME"],
 pass: process.env["USER_PASSWORD"]
});

const connection = mongoose.connection;
module.exports = connection;

And finally, the index.js file holding the main code of our server will be modified to send queries to the MongoDB database.

const express = require("express");
const app = express();
const cors = require("cors");
const connection = require("./db");

app.use(cors());
app.use(express.json());

connection.once("open", function() {
 console.log("Connection opened to database!");
})

let Choice = require("./model");

app.get("/voting", async (request, response) => {
 console.log("Get all request");
 Choice.find(function(error, result) {
 if (error) {
 console.log(error);
 } else {
 response.json(result);
 }
 });
});

app.post("/voting/:id", async (request, response) => {
 const { id } = request.params;
 console.log("Casting vote for: " + id);

 Choice.findById(id, function(error, result) {
 if (!result) {
 response.status(404).send("Choice not found");
 } else {
 result.vote_count = result.vote_count + 1;
 result.save().then(result => {
 response.json("Vote successfully cast");
 }).catch(error => {
 response.status(400).send("Failed to cast vote");
 });
 }
 });
});

app.listen(5000, async () => {
 console.log("server has started on port 5000");
});

The VotingComponent.js file in the client will be slightly modified to reference choices by their MongoDB _id parameter.

import React, { Fragment, useEffect, useState } from "react";
const fullServerUrl = "http://" + window.SERVER_URL + ":5000/voting";

const ListChoices = () => {
 const [choices, setChoices] = useState([]);

 const getChoices = async () => {...};

 useEffect(() => {...}, []);

 return (
 <Fragment>
 <h1 className="text-center mt-5">Pulumi Voting App</h1>
 {" "}
 <table className="table mt-5 text-center">
 <thead>
 <tr>
 <th>Choice</th>
 <th>Votes</th>
 </tr>
 </thead>
 <tbody>
 {choices.map(choice => (
 <tr key={choice._id}>
 <td>{choice.text}</td>
 <td>{choice.vote_count}</td>
 <td>
 <button
 className="btn btn-success"
 onClick={() => castVote(choice._id)}
 >
 Vote
 </button>
 </td>
 </tr>
 ))}
 </tbody>
 </table>
 </Fragment>
 );
};

async function castVote(id) {...}

export default ListChoices;

Now that, server, client, and database have been fully converted to use MongoDB, we can make the last remaining change in the infrastructure by updating the database deployment and service.

import * as aws from "@pulumi/aws";
import * as awsx from "@pulumi/awsx";
import * as eks from "@pulumi/eks";
import * as k8s from "@pulumi/kubernetes";
import * as pulumi from "@pulumi/pulumi";

const config = new pulumi.Config();
const sqlUserName = config.require("sql-user-name");
const sqlUserPassword = config.requireSecret("sql-user-password");
const region = aws.config.region;

const eksCluster = new eks.Cluster(...);

const ebsVolume = new aws.ebs.Volume(...);

const databaseAppName = "database-side-service";
const databaseAppLabels = { appClass: databaseAppName };
const databaseDeployment = new k8s.apps.v1.Deployment(databaseAppName, {
 metadata: { name: databaseAppName, labels: databaseAppLabels },
 spec: {
 replicas: 1,
 selector: { matchLabels: databaseAppLabels },
 template: {
 metadata: { labels: databaseAppLabels },
 spec: {
 containers: [{
 name: databaseAppName,
 image: awsx.ecr.buildAndPushImage("database-side-service", "./databaseside").image(),
 ports: [{ name: "http", containerPort: 27017 }],
 env: [
 { name: "DATABASE_NAME", value: databaseName },
 { name: "USER_NAME", value: sqlUserName },
 { name: "USER_PASSWORD", value: sqlUserPassword },

 ],
 volumeMounts: [{
 name: "persistent-volume",
 mountPath: "/persistentVolume"
 }],
 resources: {
 limits: {
 memory: "1Gi",
 cpu: "1000m"
 }
 }
 }],
 volumes: [{
 name: "persistent-volume",
 awsElasticBlockStore: {
 volumeID: ebsVolume.id,
 },
 }],
 affinity: {
 nodeAffinity: {
 requiredDuringSchedulingIgnoredDuringExecution: {
 nodeSelectorTerms: [{
 matchExpressions: [{
 key: "failure-domain.beta.kubernetes.io/zone",
 operator: "In",
 values: [ebsVolume.availabilityZone],
 }]
 }]
 }
 }
 }
 }
 },
 strategy: {
 type: "Recreate"
 }
 }}, {
 deleteBeforeReplace: true,
 provider: eksCluster.provider,
});

const databasesideListener = new k8s.core.v1.Service("database-side-listener", {
 metadata: { labels: databaseDeployment.metadata.labels },
 spec: {
 type: "ClusterIP",
 ports: [{ port: 27017, targetPort: "http" }],
 selector: databaseAppLabels,
 publishNotReadyAddresses: false,
 }}, {
 provider: eksCluster.provider,
 }
);

const mongodbAddress = databasesideListener.spec.clusterIP;

const serverAppName = "server";
const serverAppLabels = { appClass: serverAppName };
const serverDeployment = new k8s.apps.v1.Deployment("server-side-service", {
 metadata: { labels: serverAppLabels },
 spec: {
 replicas: 2,
 selector: { matchLabels: serverAppLabels },
 template: {
 metadata: { labels: serverAppLabels },
 spec: {
 containers: [{
 name: serverAppName,
 image: awsx.ecr.buildAndPushImage("server-side-service", "./serverside").image(),
 ports: [{ name: "http", containerPort: 5000 }],
 env: [
 { name: "USER_NAME", value: sqlUserName },
 { name: "USER_PASSWORD", value: sqlUserPassword },
 { name: "MONGODB_ADDRESS", value: mongodbAddress },
 { name: "MONGODB_PORT", value: String(27017) },
 { name: "DATABASE_NAME", value: databaseName },
 ],
 resources: {
 limits: {
 memory: "500Mi",
 cpu: "500m"
 }
 }
 }],
 }
 }
 }}, {
 provider: eksCluster.provider,
});

const serversideListener = new k8s.core.v1.Service(...);

const clientAppName = ...;
const clientAppLabels = { ... };
const clientDeployment = new k8s.apps.v1.Deployment(...);

const clientsideListener = new k8s.core.v1.Service(...);

To give us a simple way to connect to our application, we export the clientside listener’s address. We can now open a browser window with the URL and port number to view our application.

export const kubeConfig = eksCluster.kubeconfig;
export const URL = clientsideListener.status.loadBalancer.ingress[0].hostname;

In this example, we showed how to change a PERN stack-based application to use MERN, and demonstrated the ease with which a designer can swap out different components. The isolated nature of containerized applications allows for a great deal of modularity. It can significantly reduce the amount of time spent renovating previously written code to fit any added new components.

The MERN application code is on Github.

Migrating a cloud application to Kubernetes

Vova Ivanov — Mon, 14 Sep 2020 00:00:00 +0000

This post is outdated and contains references to a pre-release version of Pulumi Crosswalk (@pulumi/awsx). For updated AWSx documentation and examples, see the AWS Guides.

In this blog post, we will explore and demonstrate the advantages of Kubernetes by converting and deploying our PERN application to Amazon EKS. With the help of Pulumi, the process becomes greatly simplified and allows us to focus more on the big picture of designing our cloud architecture.

Kubernetes offers several distinct advantages over individually deploying Docker containers to the cloud. Firstly, it’s a robust system for minimizing downtime and rolling out updates. If a pod or node is shut down, a new one is automatically allocated to take its place. Secondly, Kubernetes can scale and distribute your infrastructure. By placing containers into pods, Kubernetes allows you to design the right cloud setup to fit your target effortlessly. And lastly, Kubernetes runs on many cloud providers, letting you choose your organization’s best cloud service provider. Since AWS, Azure, and GCP all support deploying Kubernetes, you have the option of switching if the need arises.

The first step to creating the app is to clone the Typescript PERN example. We’ll use a sparse clone to copy only the aws-ts-pern-voting-app directory.

$ mkdir examples && cd examples
$ git init
$ git remote add origin -f https://github.com/pulumi/examples/
$ git config core.sparseCheckout true
$ echo aws-ts-pern-voting-app >> .git/info/sparse-checkout
$ git pull origin master

The next step is to create a new directory and initialize a Pulumi project with pulumi new aws-typescript.

$ mkdir aws-ts-k8s-voting-app && cd aws-ts-k8s-voting-app
$ pulumi new aws-typescript

The project will require several configuration variables, which we set using pulumi config set. The variables are used to configure the PostgreSQL admin account, a user account for initializing the schema and table, and its region.

$ pulumi config set sql-admin-name <NAME>
$ pulumi config set sql-admin-password <PASSWORD> --secret
$ pulumi config set sql-user-name <NAME>
$ pulumi config set sql-user-password <PASSWORD> --secret
$ pulumi config set aws:region <REGION>

The package.json file lists the libraries used by the project. We will add the following to the dependencies section:

"@pulumi/eks": "^0.20.0",
"@pulumi/cloud-aws": "^0.19.0"

Some of the components of our Kubernetes project are nearly identical to those in the PERN application. We can copy many of these files from the example into our directory.

$ cd ..
$ cp -r aws-ts-pern-voting-app/clientside/ aws-ts-k8s-voting-app/clientside
$ cp -r aws-ts-pern-voting-app/serverside/ aws-ts-k8s-voting-app/serverside
$ cd aws-ts-k8s-voting-app

To prepare our application for Kubernetes, we create a PostgreSQL Docker container for the application. Although this is slightly more complex than directly asking AWS to provision an RDS instance, the underlying mechanics are the same for either approach.

The first step is to create two directories:

$ mkdir databaseside && cd databaseside
$ mkdir database

Like the PERN app, the outer databaseside folder holds our Dockerfile, while the inner database folder contains code.

FROM ubuntu:18.04

WORKDIR /

EXPOSE 5432

RUN apt update && \
 apt install -y postgresql

ADD database /database

CMD [ "/database/startDatabase.sh" ]

Our setup doesn’t require any files, and so the only thing we need to put in the database folder is a startDatabase.sh script that launches the database, configures users, and creates a table.

#!/bin/bash
set -exu
FILE=/persistentVolume/postgresqlDb/postgresql.conf
chown postgres:postgres /persistentVolume

if test -f "$FILE"; then
 echo "/persistentVolume already contains postgresqlDb, no need to initialize database."
else
 echo "/persistentVolume is empty, and we need to initialize the postgresql database."
 cd /persistentVolume
 su postgres -c "/usr/lib/postgresql/10/bin/initdb -D /persistentVolume/postgresqlDb"

 echo "host all all 0.0.0.0/0 md5" >> /persistentVolume/postgresqlDb/pg_hba.conf
 echo "host all all ::/0 md5" >> /persistentVolume/postgresqlDb/pg_hba.conf
 echo "listen_addresses='*'" >> /persistentVolume/postgresqlDb/postgresql.conf

 su postgres -c "/usr/lib/postgresql/10/bin/pg_ctl -D /persistentVolume/postgresqlDb --wait -l logfile start"

 set +x
 echo "psql -U postgres -c \"CREATE ROLE $ADMIN_NAME LOGIN SUPERUSER PASSWORD *********;\""
 psql -U postgres -c "CREATE ROLE $ADMIN_NAME LOGIN SUPERUSER PASSWORD '$ADMIN_PASSWORD';"
 echo "psql -U postgres -c \"CREATE USER $USER_NAME WITH PASSWORD *********;\""
 psql -U postgres -c "CREATE USER $USER_NAME WITH PASSWORD '$USER_PASSWORD';"
 echo "psql -U postgres -c \"ALTER ROLE postgres WITH NOLOGIN;\""
 psql -U postgres -c "ALTER ROLE postgres WITH NOLOGIN;"
 set -x

 psql -U $ADMIN_NAME -d postgres -c "CREATE DATABASE $DATABASE_NAME;"
 psql -U $ADMIN_NAME -d $DATABASE_NAME -c "
 CREATE SCHEMA voting_app;
 CREATE TABLE voting_app.choice(
 choice_id SERIAL PRIMARY KEY,
 text VARCHAR(255) NOT NULL,
 vote_count INTEGER NOT NULL
 );
 GRANT USAGE ON SCHEMA voting_app TO $USER_NAME;
 GRANT SELECT, UPDATE ON ALL TABLES IN SCHEMA voting_app TO $USER_NAME;
 INSERT INTO voting_app.choice (text, vote_count) VALUES('Tabs', 0);
 INSERT INTO voting_app.choice (text, vote_count) VALUES('Spaces', 0);
 "
 su postgres -c "/usr/lib/postgresql/10/bin/pg_ctl -D /persistentVolume/postgresqlDb --wait -l logfile stop"
fi

su postgres -c "/usr/lib/postgresql/10/bin/postgres -D /persistentVolume/postgresqlDb"

Because we don’t have any SSL certificates to authenticate and encrypt internet traffic, the way the server connects to the database needs to be modified to include an ssl: false pool parameter.

const Pool = require("pg").Pool;

const pool = new Pool({
 user: process.env["USER_NAME"],
 password: process.env["USER_PASSWORD"],
 host: process.env["POSTGRES_ADDRESS"],
 port: process.env["POSTGRES_PORT"],
 database: process.env["DATABASE_NAME"],
 ssl: false,
});

module.exports = pool;

With our server, client, and database in place, we can focus on the infrastructure. We start with importing libraries and describing the application’s configuration options.

import * as aws from "@pulumi/aws";
import * as awsx from "@pulumi/awsx";
import * as eks from "@pulumi/eks";
import * as k8s from "@pulumi/kubernetes";
import * as pulumi from "@pulumi/pulumi";

const config = new pulumi.Config();
const sqlAdminName = config.require("sql-admin-name");
const sqlAdminPassword = config.requireSecret("sql-admin-password");
const sqlUserName = config.require("sql-user-name");
const sqlUserPassword = config.requireSecret("sql-user-password");
const awsConfig = new pulumi.Config("aws");
const region = aws.config.region;

The central part of our application is an AWS Elastic Kubernetes Cluster. It holds our application and dictates how many nodes should be allocated for the processes running inside the cluster.

const eksCluster = new eks.Cluster("eksCluster", {
 name: "eksCluster",
 instanceType: "t2.medium",
 desiredCapacity: 3,
 minSize: 2,
 maxSize: 4,
 deployDashboard: false,
 enabledClusterLogTypes: [
 "api",
 "audit",
 "authenticator",
 ],
});

Kubernetes nodes use ephemeral storage. When Pods shut down or get restarted, everything is erased. To create a permanent storage system suitable for our database, we need a Persistent Volume instance.

const ebsVolume = new aws.ebs.Volume("storage-volume", {
 size: 1,
 type: "gp2",
 availabilityZone: region + "a",
 encrypted: true,
 }, {
 protect: false,
});

Now that the infrastructure for our database is ready, we can launch a PostgreSQL server on the cloud in the form of a Deployment. Deployments offer a multitude of customization options ranging from attaching volumes, setting the memory and cpu requirements, to specifying which deployments can and cannot be run on the same node.

const databaseAppName = "database-side-service";
const databaseAppLabels = { appClass: databaseAppName };
const databaseDeployment = new k8s.apps.v1.Deployment(databaseAppName, {
 metadata: { name: databaseAppName, labels: databaseAppLabels },
 spec: {
 replicas: 1,
 selector: { matchLabels: databaseAppLabels },
 template: {
 metadata: { labels: databaseAppLabels },
 spec: {
 containers: [{
 name: databaseAppName,
 image: awsx.ecr.buildAndPushImage("database-side-service", "./databaseside").image(),
 ports: [{ name: "http", containerPort: 5432 }],
 env: [
 { name: "ADMIN_NAME", value: sqlAdminName },
 { name: "ADMIN_PASSWORD", value: sqlAdminPassword },
 ],
 volumeMounts: [{
 name: "persistent-volume",
 mountPath: "/persistentVolume"
 }],
 resources: {
 limits: {
 memory: "1Gi",
 cpu: "1000m"
 }
 }
 }],
 volumes: [{
 name: "persistent-volume",
 awsElasticBlockStore: {
 volumeID: ebsVolume.id,
 },
 }],
 affinity: {
 nodeAffinity: {
 requiredDuringSchedulingIgnoredDuringExecution: {
 nodeSelectorTerms: [{
 matchExpressions: [{
 key: "failure-domain.beta.kubernetes.io/zone",
 operator: "In",
 values: [ebsVolume.availabilityZone],
 }]
 }]
 }
 }
 }
 }
 },
 strategy: {
 type: "Recreate"
 }
 }}, {
 deleteBeforeReplace: true,
 provider: eksCluster.provider,
});

In order to have a a way for the pods in cluster to communicate with our database, we create a Kubernetes service for it. It is best practice to keep databases and other similar components entirely within the cluster, and not allow them to be accessed directly the internet.

const databasesideListener = new k8s.core.v1.Service("database-side-listener", {
 metadata: { labels: databaseDeployment.metadata.labels },
 spec: {
 type: "ClusterIP",
 ports: [{ port: 5432, targetPort: "http" }],
 selector: databaseAppLabels,
 publishNotReadyAddresses: false,
 }}, {
 provider: eksCluster.provider,
 }
);

const postgresqlAddress = databasesideListener.spec.clusterIP;
});

Now, all that remains is deploying the client and server containers to Kubernetes. Since the PERN application already deployed them as docker containers, it doesn’t take much effort to reconfigure it for Kubernetes. Unlike the database, these components can safely be open to the Internet using a service with a Load Balancer type.

We’ll first set up the server deployment:

const serverAppName = "server";
const serverAppLabels = { appClass: serverAppName };
const serverDeployment = new k8s.apps.v1.Deployment("server-side-service", {
 metadata: { labels: serverAppLabels },
 spec: {
 replicas: 2,
 selector: { matchLabels: serverAppLabels },
 template: {
 metadata: { labels: serverAppLabels },
 spec: {
 containers: [{
 name: serverAppName,
 image: awsx.ecr.buildAndPushImage("server-side-service", "./serverside").image(),
 ports: [{ name: "http", containerPort: 5000 }],
 env: [
 { name: "USER_NAME", value: sqlUserName },
 { name: "USER_PASSWORD", value: sqlUserPassword },
 { name: "POSTGRES_ADDRESS", value: postgresqlAddress },
 { name: "POSTGRES_PORT", value: String(5432) },
 { name: "DATABASE_NAME", value: postgresDatabase.name },
 ],
 resources: {
 limits: {
 memory: "500Mi",
 cpu: "500m"
 }
 }
 }],
 }
 }
 }}, {
 provider: eksCluster.provider,
});

const serversideListener = new k8s.core.v1.Service("server-side-listener", {
 metadata: { labels: serverDeployment.metadata.labels },
 spec: {
 type: "LoadBalancer",
 ports: [{ port: 5000, targetPort: "http" }],
 selector: serverAppLabels,
 publishNotReadyAddresses: false,
 }}, {
 provider: eksCluster.provider,
 }
);

And lastly, the client deployment.

const clientAppName = "client";
const clientAppLabels = { appClass: clientAppName };
const clientDeployment = new k8s.apps.v1.Deployment("client-side-service", {
 metadata: { labels: clientAppLabels },
 spec: {
 replicas: 2,
 selector: { matchLabels: clientAppLabels },
 template: {
 metadata: { labels: clientAppLabels },
 spec: {
 containers: [{
 name: clientAppName,
 image: awsx.ecr.buildAndPushImage("client-side-service", "./clientside").image(),
 ports: [{ name: "http", containerPort: 3000 }],
 env: [
 { name: "SERVER_HOSTNAME", value: serversideListener.status.loadBalancer.ingress[0].hostname },
 ],
 resources: {
 limits: {
 memory: "500Mi",
 cpu: "500m"
 }
 },
 }],
 }
 }
 }}, {
 provider: eksCluster.provider,
});

const clientsideListener = new k8s.core.v1.Service("client-side-listener", {
 metadata: { labels: clientDeployment.metadata.labels },
 spec: {
 type: "LoadBalancer",
 ports: [{ port: 3000, targetPort: "http" }],
 selector: clientAppLabels,
 publishNotReadyAddresses: false,
 }}, {
 provider: eksCluster.provider,
 }
);

To give us a simple way to connect to our application, we export the clientside listener’s address. We can now open a browser window with the URL and port number to view our application.

export const kubeConfig = eksCluster.kubeconfig;
export const URL = clientsideListener.status.loadBalancer.ingress[0].hostname;

In this example, we demonstrated the benefits Kubernetes offers and showed how to use Pulumi to deploy an application to Kubernetes hosted on AWS. Although it might seem unnecessary to use such a system for only a single voting app, the advantages of running your project in the form of containerized services become apparent as your application grows in size.

Next week, we’ll explore applications using the MERN stack: MongoDB, Express, React, and NodeJS.

The blog post’s code can be found on Github.

Deploying a PERN stack application to AWS

Vova Ivanov — Fri, 04 Sep 2020 00:00:00 +0000

Some of the code in this post is out of date. See the AWS guides for an updated overview and examples.

In this blog post, we will explore PERN stack applications and deploy one to AWS. PERN is an acronym for PostgreSQL, Express, React, and Node. A PERN stack application is a project that uses PostgreSQL, Express as an application framework, React as a user interface framework, and runs on Node. We will also use Pulumi Crosswalk to reduce the amount of code and provide a quick and straightforward path for deploying the application.

PERN projects have four distinct tiers:

a database that keeps track of our data,
a stateless server that receives commands to manage the database,
a clientside server that contains and renders the user interface code,
and the users who run the code in their browsers and send requests to the stateless server.

An advantage of infrastructure as code is that the application and infrastructure deployment can use the same language. As React and the other components use NodeJS, we’ll use it for our infrastructure by writing it in TypeScript. The first step is to create a new directory and initialize a Pulumi project with pulumi new aws-typescript.

$ mkdir aws-ts-pern-voting-app && cd aws-ts-pern-voting-app
$ pulumi new aws-typescript

This tutorial was written for the aws-ts-pern-voting-app example but will work with any other PERN stack application. The example uses two folders to hold the client and server tiers and a Dockerfile that builds images that run as containers in AWS.

To deploy our PERN stack, the project requires several configuration variables, which we set using pulumi config set. The variables are used to configure the PostgreSQL admin account, a user account for initializing the schema and table, and the database’s region.

$ pulumi config set sql-admin-name <NAME>
$ pulumi config set sql-admin-password <PASSWORD> --secret
$ pulumi config set sql-user-name <NAME>
$ pulumi config set sql-user-password <PASSWORD> --secret
$ pulumi config set aws:region <REGION>

The package.json file lists the libraries used by the project. We will add the following to the dependencies section:

"@pulumi/cloud-aws": "^0.19.0",
"@pulumi/postgresql": "^2.3.0",
"pg": "^8.3.3"

Our project uses a Dynamic Provider to help create tables and Schemas. It offers the same features as our MySQL provider, but for PostgreSQL.

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

export interface SchemaInputs {
 creatorName: pulumi.Input<string>
 creatorPassword: pulumi.Input<string>
 serverAddress: pulumi.Input<string>
 databaseName: pulumi.Input<string>
 creationScript: pulumi.Input<string>
 deletionScript: pulumi.Input<string>
 postgresUserName: pulumi.Input<string>
}

export class SchemaProvider implements pulumi.dynamic.ResourceProvider {
 async create(args: SchemaInputs): Promise<pulumi.dynamic.CreateResult> {
 const { Pool } = require("pg");
 const pool = new Pool({
 user: args.creatorName,
 password: args.creatorPassword,
 host: args.serverAddress,
 port: 2000,
 database: args.databaseName
 });
 const scriptExecuted = await pool.query(args.creationScript);

 await pool.end();
 return {id: "postgresqlSchema-" + crypto.randomBytes(16).toString('hex'), outs: args};
 }

 async delete(id: string, args: SchemaInputs): Promise<void> {
 const { Pool } = require("pg");
 const pool = new Pool({
 user: args.creatorName,
 password: args.creatorPassword,
 host: args.serverAddress,
 port: 2000,
 database: args.databaseName
 });
 const scriptExecuted = await pool.query(args.deletionScript);
 await pool.end();
 }

 async diff(id: string, oldArgs: SchemaInputs, newArgs: SchemaInputs): Promise<pulumi.dynamic.DiffResult> {
 let changes: boolean = ((oldArgs.creatorName != newArgs.creatorName) ||
 (oldArgs.creatorPassword != newArgs.creatorPassword) || (oldArgs.serverAddress != newArgs.serverAddress) ||
 (oldArgs.databaseName != newArgs.databaseName) || (oldArgs.creationScript != newArgs.creationScript) ||
 (oldArgs.deletionScript != newArgs.deletionScript));

 let replaces: string[] = [];
 if (oldArgs.serverAddress != newArgs.serverAddress) { replaces.push("serverAddress") };
 if (oldArgs.databaseName != newArgs.databaseName) { replaces.push("databaseName") };
 if (oldArgs.creationScript != newArgs.creationScript) { replaces.push("creationScript") };

 return {
 changes: changes,
 replaces: replaces,
 stables: [],
 deleteBeforeReplace: true
 }
 }

 async update(id: string, oldArgs: SchemaInputs, newArgs: SchemaInputs): Promise<pulumi.dynamic.UpdateResult> {
 return { outs: newArgs };
 }
}

export class Schema extends pulumi.dynamic.Resource {
 public readonly creatorName!: pulumi.Output<string>;
 public readonly creatorPassword!: pulumi.Output<string>;
 public readonly serverAddress!: pulumi.Output<string>;
 public readonly databaseName!: pulumi.Output<string>;
 public readonly creationScript!: pulumi.Output<string>;
 public readonly deletionScript!: pulumi.Output<string>;
 constructor(name: string, args: SchemaInputs) {
 super(new SchemaProvider, name, args);
 }
}

With the Dynamic provider configured, we can focus on the main index.ts file. We start with importing libraries and describing the application’s configuration options.

import * as aws from "@pulumi/aws";
import * as awsx from "@pulumi/awsx";
import * as pulumi from "@pulumi/pulumi";
import * as postgresql from "@pulumi/postgresql";
import { Schema } from "./PostgreSqlDynamicProvider";
import { table } from "console";

const config = new pulumi.Config();
const sql_admin_name = config.require("sql-admin-name");
const sql_admin_password = config.requireSecret("sql-admin-password");
const sql_user_name = config.require("sql-user-name");
const sql_user_password = config.requireSecret("sql-user-password");
const awsConfig = new pulumi.Config("aws");
const availabilityZone = awsConfig.get("region");

Apart from language differences, the code for creating the VPC, subnets, and tables is almost identical to our previous projects. Since we will be using Crosswalk, we can leave out a few components that will be automatically created later.

const appVpc = new aws.ec2.Vpc("app-vpc", {
 cidrBlock: "172.31.0.0/16",
 enableDnsHostnames: true
});

const appGateway = new aws.ec2.InternetGateway("app-gateway", {
 vpcId: appVpc.id
});

const appRoutetable = new aws.ec2.RouteTable("app-routetable", {
 routes: [
 {
 cidrBlock: "0.0.0.0/0",
 gatewayId: appGateway.id,
 }
 ],
 vpcId: appVpc.id
});

const appRoutetableAssociation = new aws.ec2.MainRouteTableAssociation("app-routetable-association", {
 routeTableId: appRoutetable.id,
 vpcId: appVpc.id
});

const rdsSecurityGroup = new aws.ec2.SecurityGroup("rds-security-group", {
 vpcId: appVpc.id,
 description: "Enables HTTP access",
 ingress: [{
 protocol: 'tcp',
 fromPort: 0,
 toPort: 65535,
 cidrBlocks: ['0.0.0.0/0'],
 }],
 egress: [{
 protocol: '-1',
 fromPort: 0,
 toPort: 0,
 cidrBlocks: ['0.0.0.0/0'],
 }]
});

const firstRdsSubnet = new aws.ec2.Subnet("first-rds-subnet", {
 vpcId: appVpc.id,
 cidrBlock: "172.31.0.0/20",
 availabilityZone: availabilityZone + "a"
});

const secondRdsSubnet = new aws.ec2.Subnet("second-rds-subnet", {
 vpcId: appVpc.id,
 cidrBlock: "172.31.128.0/20",
 availabilityZone: availabilityZone + "b"
});

We create a SubnetGroup and an RDS instance. The latter uses PostgreSQL instead of MySQL, and is assigned 2000.

const rdsSubnetGroup = new aws.rds.SubnetGroup("rds-subnet-group", {
 subnetIds: [firstRdsSubnet.id, secondRdsSubnet.id]
});

const postgresqlRdsServer = new aws.rds.Instance("postgresql-rds-server", {
 engine: "postgres",
 username: sql_admin_name,
 password: sql_admin_password,
 instanceClass: "db.t2.micro",
 allocatedStorage: 20,
 skipFinalSnapshot: true,
 publiclyAccessible: true,
 port: 2000,
 dbSubnetGroupName: rdsSubnetGroup.name,
 vpcSecurityGroupIds: [rdsSecurityGroup.id]
});

Pulumi offers additional tools to make handling PostgreSQL easier.

const postgresqlProvider = new postgresql.Provider("postgresql-provider", {
 host: postgresqlRdsServer.address,
 port: postgresqlRdsServer.port,
 username: sql_admin_name,
 password: sql_admin_password,
 superuser: false
});

We initialize the example database and create a user to manage it.

const postgresDatabase = new postgresql.Database("postgresql-database", {
 name: "votes"}, {
 provider: postgresqlProvider
});

const postgresUser = new postgresql.Role("postgres-standard-role", {
 name: sql_user_name,
 password: sql_user_password,
 superuser: false,
 login: true,
 connectionLimit: -1}, {
 provider: postgresqlProvider
});

We use the Dynamic provider to create a schema and a table, grant permissions for our user to edit and select it, and populate the table with two initial voting options.

const creation_script = `
 CREATE SCHEMA voting_app;
 CREATE TABLE voting_app.choice(
 choice_id SERIAL PRIMARY KEY,
 text VARCHAR(255) NOT NULL,
 vote_count INTEGER NOT NULL
 );
 GRANT USAGE ON SCHEMA voting_app TO ${sql_user_name};
 GRANT SELECT, UPDATE ON ALL TABLES IN SCHEMA voting_app TO ${sql_user_name};
 INSERT INTO voting_app.choice (text, vote_count) VALUES('Tabs', 0);
 INSERT INTO voting_app.choice (text, vote_count) VALUES('Spaces', 0);
`;

const deletion_script = "DROP SCHEMA IF EXISTS voting_app CASCADE";

const postgresqlVotesTable = new Schema("postgresql-votes-schema", {
 creatorName: sql_admin_name,
 creatorPassword: sql_admin_password,
 serverAddress: postgresqlRdsServer.address,
 databaseName: postgresDatabase.name,
 creationScript: creation_script,
 deletionScript: deletion_script,
 postgresUserName: postgresUser.name
});

With the basic infrastructure and provider completed, we can write the application deployment code to ECS. We will use Pulumi Crosswalk, a collection of libraries that makes common infrastructure-as-code tasks in AWS easier and more secure by automatically using well-architected best practices.

We’ll first set up the server. The Network Listener is assigned the same port as the server, which is, in our case, port 5000. A set of environment variables representing our PostgreSQL connection credentials are passed directly to the awsx.ecs.FargateService. With AWS Crosswalk, what would have been over 150 lines of code is reduced to just under 20 lines of code.

const serversideListener = new awsx.elasticloadbalancingv2.NetworkListener("server-side-listener", { port: 5000 });
const serversideService = new awsx.ecs.FargateService("server-side-service", {
 taskDefinitionArgs: {
 containers: {
 serversideService: {
 image: awsx.ecs.Image.fromPath("server-side-service", "./serverside"),
 memory: 512,
 portMappings: [serversideListener],
 environment: [
 { name: "USER_NAME", value: sql_user_name },
 { name: "USER_PASSWORD", value: sql_user_password },
 { name: "RDS_ADDRESS", value: postgresqlRdsServer.address },
 { name: "RDS_PORT", value: String(2000) },
 { name: "DATABASE_NAME", value: postgresDatabase.name },
 ],
 },
 },
 },
});

The same is true for the client service, which is reduced to a short and easy to understand format. By default, React uses port 3000, but it can set to a different port. The SERVER_HOSTNAME environment variable is passed in when the container starts to generate a tiny configuration file at runtime called serverParams.js with the URL. This way, we do not have to rebuild the entire docker image should the server URL change.

const clientsideListener = new awsx.elasticloadbalancingv2.NetworkListener("client-side-listener", { port: 3000 });
const clientsideService = new awsx.ecs.FargateService("client-side-service", {
 taskDefinitionArgs: {
 containers: {
 clientsideService: {
 image: awsx.ecs.Image.fromPath("client-side-service", "./clientside"),
 memory: 512,
 portMappings: [clientsideListener],
 environment: [
 { name: "SERVER_HOSTNAME", value: serversideListener.endpoint.hostname },
 ],
 },
 },
 },
});

To make our PERN stack application available on the Internet, we export the clientside listener’s address. We can open a browser window with the URL and port to view our application.

export const URL = clientsideListener.endpoint.hostname;

In this example, I explained the basic principles behind PERN stack applications and showed how to create the infrastructure to deploy them on ECS. A flexible and optimized tool, Pulumi Crosswalk supports rapidly prototyping applications, scaling workloads, securing and integrating applications in existing infrastructure, and going to production in multiple complex environments.

Next week, I’ll demonstrate how to integrate applications with Kubernetes, and seamlessly deploy them to EKS using Pulumi.

The blog post’s code can be found on Github.

Getting Started on DigitalOcean with Pulumi

Paul Stack — Thu, 18 Jul 2019 00:00:00 +0000

Pulumi recently added support for managing DigitalOcean resources. This article will show you how to deploy some load balanced Droplets on DigitalOcean using Pulumi.

To get started, let’s create a new Pulumi program written in TypeScript:

 $ mkdir infra && cd infra
 $ pulumi new typescript

Now we should install the latest Pulumi DigitalOcean provider:

 $ npm install @pulumi/digitalocean

At the top of our application, we can add the resource imports:

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

We can now start to build the infrastructure. To get started, we will declare two constants:

const dropletCount = 3;
const region = digitalocean.Regions.NYC3;

Now, let’s create our web servers. Since our Pulumi application is written in TypeScript, we can use a loop, as follows:

const dropletTypeTag = new digitalocean.Tag("demo-app");
const userData =
 `#!/bin/bash
 sudo apt-get update
 sudo apt-get install -y nginx`;

const droplets = [];
for (let i = 0; i < dropletCount; i++) {
 let nameTag = new digitalocean.Tag(`web-${i}`);

 droplets.push(new digitalocean.Droplet(`web-${i}`, {
 image: "ubuntu-18-04-x64",
 region: region,
 privateNetworking: true,
 size: digitalocean.DropletSlugs.Droplet512mb,
 tags: [nameTag.id, dropletTypeTag.id],
 userData: userData,
 }));
}

Let’s take a closer look at what we’ve programmed. First, we declared a dropletTypeTag; we’ll come back to what this tag signifies later. Next, we have a userData constant that we can pass to all the instances, so that we can see they are running a web server. Then, we are declaring a nameTag constant. This allows us to use the interpolation in the loop to ensure that each of our Droplets is tagged with the appropriate name. We can also see that the region constant is being used in the Droplet declaration and we are adding the meta-information back to the Droplets array for later use.

Our next piece of infrastructure is our load balancer. We are going to create a public load balancer that will accept connections on port 80 and forward those connections to the Droplets that are attached on port 80. The infrastructure block looks like this:

const lb = new digitalocean.LoadBalancer("public", {
 dropletTag: dropletTypeTag.name,
 forwardingRules: [{
 entryPort: 80,
 entryProtocol: digitalocean.Protocols.HTTP,
 targetPort: 80,
 targetProtocol: digitalocean.Protocols.HTTP,
 }],
 healthcheck: {
 port: 80,
 protocol: digitalocean.Protocols.TCP,
 },
 region: region,
});

export const endpoint = lb.ip;

The configuration is made up of an array of forwarding rules. Here, we forward traffic from the load balancer to the Droplets. Then we have a health check that makes sure that port 80 is actually available and we deploy the load balancer into the region that we declared as a constant earlier. The interesting thing about load balancers in DigitalOcean is that you can attach instances by Droplet tag without knowing the Droplet IDs. Here, we configure all Droplets that have the tag demo-app, in this region, to be attached to the load balancer.

Running this gives us:

Updating (dev):

 Type Name Status
 + pulumi:pulumi:Stack do-ref-architecture-dev created
 + ├─ digitalocean:index:Tag web-0 created
 + ├─ digitalocean:index:Tag web-1 created
 + ├─ digitalocean:index:Tag web-2 created
 + ├─ digitalocean:index:Tag demo-app created
 + ├─ digitalocean:index:Droplet web-0 created
 + ├─ digitalocean:index:Droplet web-1 created
 + ├─ digitalocean:index:LoadBalancer public created
 + └─ digitalocean:index:Droplet web-2 created

Outputs:
 endpoint: "45.55.120.64"

Resources:
 + 9 created

Duration: 3m5s

You should be able to take the endpoint address and put it into the browser or you should be able to curl it as follows:

curl "$(pulumi stack output endpoint)"

We are constantly working on ways to make Pulumi more productive to use with DigitalOcean. Pulumi is free and open source. You can get started with Pulumi today at https://www.pulumi.com.

Get Started with Docker on AWS Fargate using Pulumi

Joe Duffy — Tue, 30 Apr 2019 00:00:00 +0000

Some of the code in this post is out of date. See the AWS guides for an updated overview and examples.

Update: Check out the Learning Machine Case Study where provisioning went from 3 weeks to 1 hour with Pulumi and AWS.

“The impact of serverless capabilities was also transformative for the Learning Machine business. Pulumi enabled a rapid shift to Amazon ECS, AWS Fargate and AWS Lambda — the net effect of which was a 67% reduction in AWS charges. This enabled the team to spend less time focused on maintaining existing infrastructure and more time deploying new applications on AWS and adding new customers.

Pulumi is the foundational technology that allowed us to transform our organization,” said Hughes. The entire DevOps process was streamlined and in addition to realizing better productivity and higher quality, the team has new insight into their SaaS offering that they never thought possible.”

The Docker Getting Started tutorial shows how to develop, build, and run a modern containerized application, from a single custom Docker container published to the Docker Hub, to a scaled out service with load balancing. But there are challenges: it requires you to program in YAML, run (or script) many CLI commands, and manage your own Swarm or Kubernetes cluster. There is an easier way. By using Pulumi’s infrastructure as code, we can build a custom Docker image, publish it to a private AWS container registry, and spin up an AWS Fargate load balanced service running that container, all in 28 lines of TypeScript code and a single pulumi up command. The result leverages the best of what AWS has to offer, with the entire platform at your fingertips, with a single approach. In this article, we’ll see how.

Defining Everything in Code

The Docker Getting Started tutorial goes from a simple developer desktop scenario to a fully scaled out service in production. There is a lot of ceremony, however: YAML, many CLI commands, running your own Swarm cluster by hand, etc. This is complicated and doesn’t lend itself to repeatable deployments across many environments.

What if we could just write 28 lines of TypeScript instead, and accomplish the same end result, while leveraging the latest innovations in the AWS platform, natively?

In fact, we can. This article will show you how Pulumi’s infrastructure as code solution enables exactly this.

*Note: Everything we’re about to define will be in a single TypeScript file, index.ts. Other languages are available, including using plain Node.js JavaScript. Pulumi also supports other clouds, including Azure and GCP, however to fully exploit the power of the underlying AWS platform, these examples will leverage native capabilities like VPCs, ALBs, and Fargate.

To cut to the chase, here is the entire program. We’ll spend the rest of the post walking through it line by line:

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

// Step 1: Create an ECS Fargate cluster.
const cluster = new awsx.ecs.Cluster("cluster");

// Step 2: Define the Networking for our service.
const alb = new awsx.lb.ApplicationLoadBalancer(
    "net-lb", { external: true, securityGroup: cluster.securityGroup });
const web = alb.createListener("web", { port: 80, external: true });

// Step 3: Build and publish a Docker image to a private ECR registry.
const img = awsx.ecs.Image.fromPath("app-img", "./app");

// Step 4: Create a Fargate service task that can scale out.
const appService = new awsx.ecs.FargateService("app-svc", {
    cluster,
    taskDefinitionArgs: {
        container: {
            image: img,
            cpu: 102 /*10% of 1024*/,
            memory: 50 /*MB*/,
            portMappings: [ web ],
        },
    },
    desiredCount: 5,
});

// Step 5: Export the Internet address for the service.
export const url = web.endpoint.hostname;

Step 1. Create a Cluster

The opening stanza imports Pulumi’s open source AWSX NPM package, @pulumi/awsx. It contains high level AWS best practices and patterns, and leverages real languages to eliminate boilerplate YAML templating:

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

To provision an entire Elastic Container Service (ECS) cluster, AWS’s native container orchestration technology, we just new one up in a single line of code:

const cluster = new awsx.ecs.Cluster("cluster");

This will use the default Virtual Private Cloud (VPC) in our account. If we want to customize this aspect along with the auto-scaling policies, we can easily override the defaults by passing the appropriate arguments.

Step 2. Define the Networking

Next we need to think about the networking for our desired application. First, we will need a load balancer, as we’re going to create a scaled-out application and want a fixed address. Second, we will want to expose port 80 to the Internet, for incoming traffic. This leads to these two lines:

const alb = new awsx.lb.ApplicationLoadBalancer(
    "net-lb", { external: true, securityGroups: cluster.securityGroups });
const web = lb.createListener("web", { port: 80, external: true });

An Elastic Application Load Balancer (ALB) in AWS is a fully featured Layer 7 load balancer, with advanced features around SSL termination, content based routing, and HTTP/2. The AWSX package enables you to whip together simple routing when appropriate, while still having the ability to dig deeper into the advanced capabilities as you scale your workload to handle more sophisticated scenarios. Simple things simple, hard things possible!

Step 3. Build and Publish the Container Image

The next line declares a Docker image:

const img = awsx.ecs.Image.fromPath("app-img", "./app");

This single line is quite the work horse, and does a lot. Let’s unpack it a bit.

First and foremost, this allocates a private Elastic Container Registry (ECR) repository for your Docker image. This is AWS’s hosted Docker registry solution, privately encapsulated inside your AWS account.

But there is more: this also builds the Dockerfile underneath ./app and publishes the result to said registry, each time you run pulumi up! Any Dockerfile will work. This means you get a single command line to both provision and update your infrastructure, in addition to publishing and rolling out your images.

Step 4. Create a Scale-Out Service

Next up, let’s deploy our published image as a containerized service, behind our load balanced network on port 80, using our ECS Fargate cluster. Fargate is a managed container orchestrator that lets us skip the messy details of installing and managing Swarm on our own. This effectively replaces the docker-compose.yml from the Docker Getting Started tutorial, with a similarly simple sequence of code, and which gives us full access to the AWS platform:

const appService = new awsx.ecs.FargateService("app-svc", {
    cluster,
    taskDefinitionArgs: {
        container: {
            image: img,
            cpu: 128 /*~10%*/,
            memory: 50 /*MB*/,
            portMappings: [ web ],
        },
    },
    desiredCount: 5,
});

Notice that img just refers to the Docker image built in Step 3, and the portMappings structure references our load balancer’s listener defined in Step 2. Pulumi tracks all the dependencies so that it knows how to perform deployment activities in the right order. The task definition structure here exposes all of the underlying AWS ECS capabilities.

Step 5. Deploy the App and Kick the Tires!

On to the final step! Let’s deploy our infrastructure and application, and kick the tires.

The last line of code exposes the load balancer address so it’s easy to access:

export const url = web.endpoint.hostname;

The net result is that, with this project defined with the 28 lines of code above, we can simply run pulumi up; this command will show us a preview of the changes it will make and then, once confirmed, deploy everything to our AWS account, and hand back our service’s hostname:

After deploying everything, you’ve got a fully functioning application. To give it a try, let’s grab the URL exported by our program from the stack output command, and curl it:

$ curl http://$(pulumi stack output url)
<h3>Hello World!</h3>
<b>Hostname:</b> ip-172-31-39-18.ec2.internal<br/>
<b>Visits:</b> <i>cannot connect to Redis, counter disabled</i>

Or open it in our web browser:

$ open http://$(pulumi stack output url)

As an added bonus, the entire time we are doing these deployments, the Pulumi Service is keeping track of deployment state, to ensure everything works reliably and in a team setting, similar to how Git works with GitHub. For example, I can see a history of my deployments:

Congratulations!

In this article, you’ve seen how to take 28 lines of code, and turn them, plus a Dockerfile, into a fully functioning AWS microservice, including the infrastructure and application resources. No YAML required, no complex sequence of CLI commands, and no manual cluster installation.

Pulumi’s “everything is code” approach means deploying everything can be done with a CLI command, unlocking the power of the entire Docker platform with a great inner development loop, that works from the desktop all the way to production. This entire flow can be easily integrated into your favorite CI/CD pipeline, including GitOps workflows.

If we want to augment our service with other AWS resources – like S3 buckets, Aurora or RDS databases, Lambda functions, CloudWatch dashboards, etc – they can be provisioned and managed the same was created our clusters and load balancers: just new them up!

Remember that all of this not only works for native AWS ECS containers, but also Azure and GCP cloud providers, in addition to Kubernetes!

Want to go deeper?

Kubernetes RBAC in AWS EKS with open source Pulumi packages

Nishi Davidson — Wed, 24 Apr 2019 00:00:00 +0000

Check out version 3.0 of the Pulumi EKS Provider.

One of the most common areas Kubernetes operators struggle with in production involves creating and managing role-based access control (RBAC). This is so daunting that RBAC is often not implemented, or implemented halfway, or the configuration becomes impossible to maintain.

Fortunately, Pulumi makes RBAC on Kubernetes so easy that you’ll never create an insecure cluster again. In this post, we will contrast the traditional way of working with RBAC on EKS with using Pulumi.

Here are a few highlights:

NO MORE YAMLs! Configuring YAMLs, operators or custom resources is now a thing in the past! You use TypeScript or JavaScript to program directly with our cloud SDK and connect all cloud services to your Kubernetes services with a simple reference to the object in your program.
INCREASED DEVELOPMENT VELOCITY: You intuitively program Kubernetes objects with our SDK abstractions using minimal amount of code within hours instead of months. You “autocomplete” AWS, EKS, Kubernetes specifications within your IDE without understanding the entire API.
EASY UPDATES: Changing a roleRef in a RoleBinding, on one or multiple clusters involves updating your TypeScript file index.ts and running pulumi up. The Pulumi Service allows you to share your stack with your team in your GitHub, GitLab, or Atlassian-based organization.
WORKFLOW AUTOMATION FOR RBAC AT SCALE: You can delete or update multiple RoleBindings or Roles from your Pulumi stack source code. As you commit these changes to your repository, you can plan automated triggers that validate such changes as part of your CI/CD flow, whether you use Travis, CircleCI, AzureDevOps and more. Pulumi even has a GitHub Application for surfacing results within pull requests.

Prerequisites to work with Pulumi

Install pulumi CLI and set up your AWS credentials. Initialize a new Pulumi project from available templates. We use aws-typescript template here to install all dependencies and save the configuration.

$ brew install pulumi/tap/pulumi # download pulumi CLI
$ mkdir eks-rbac && cd eks-rbac
$ pulumi new aws-typescript
$ ls -l
-rw-r--r-- 1 nishidavidson staff 32 Apr 18 14:49 Pulumi.dev.yaml
-rw------- 1 nishidavidson staff 84 Apr 18 14:48 Pulumi.yaml
-rw------- 1 nishidavidson staff 273 Apr 18 14:48 index.ts
drwxr-xr-x 92 nishidavidson staff 2944 Apr 18 14:49 node_modules
-rw-r--r-- 1 nishidavidson staff 48352 Apr 18 14:49 package-lock.json
-rw------- 1 nishidavidson staff 228 Apr 18 14:48 package.json
-rw------- 1 nishidavidson staff 522 Apr 18 14:48 tsconfig.json

With Pulumi, you will modify and update the default index.ts file with AWS and EKS resource variable declarations. We show you how to add this code as we contrast Pulumi’s approach with the sequential traditional approach in the steps below. In the end, you will do a one-time run of pulumi up and watch all the steps in the Traditional Way come alive simultaneously.

Step 1: Create three IAM Roles with a Trust-policy to map to Amazon EKS RBAC.

The Traditional-approach:

You sequentially create three IAM roles (clusterAdminRole; AutomationRole; EnvProdRole) with aws command line tool as shown below:

$ aws iam create-role --role-name clusterAdminRole --assume-role-policy-document file://Role-Trust-Policy.json
 
{
    "Role": {
        "AssumeRolePolicyDocument": {
            "Version": "2012-10-17",
            "Statement": [
                {
                    "Action": "sts:AssumeRole",
                    "Principal": {
                        "AWS": "arn:aws:iam::xxxxxxxxxxxx:root"
                    },
                    "Effect": "Allow",
                    "Sid": ""
                }
            ]
        },
        "RoleId": "AROASHIVKXX3SFFMUUEU6",
        "CreateDate": "2019-04-17T17:43:03Z",
        "RoleName": "clusterAdminRole",
        "Path": "/",
        "Arn": "arn:aws:iam::xxxxxxxxxxxx:role/clusterAdminRole"
    }
}
 
$ cat Role-Trust-Policy.json
{
    "Version": "2012-10-17",
    "Statement": [
        {
          "Effect": "Allow",
          "Action": "sts:AssumeRole",
          "Resource": "*"
        }
    ]
}

The Pulumi-approach:

You update the default index.ts file in your source code editor such as VSCode as follows:

import * as aws from "@pulumi/aws";
import * as awsx from "@pulumi/awsx";
import * as eks from "@pulumi/eks";
import * as k8s from "@pulumi/kubernetes";

/*
 * 1) Single step deployment of three IAM Roles
 */

function createIAMRole(name: string): aws.iam.Role {
    // Create an IAM Role...
    return new aws.iam.Role(`${name}`, {
        assumeRolePolicy: `{
            "Version": "2012-10-17",
            "Statement":[
              {
                "Sid": "",
                "Effect": "Allow",
                "Principal": {
                  "AWS": "arn:aws:iam::153052954103:root"
                },
                "Action": "sts:AssumeRole"
              }
            ]
           }
        `,
          tags: {
              "clusterAccess": `${name}-usr`,
          },
        });
    };
}

// Administrator AWS IAM clusterAdminRole with full access to all AWS resources
const clusterAdminRole = createIAMRole("clusterAdminRole");

// Administer Automation role for use in pipelines, e.g. gitlab CI, Teamcity, etc.
const AutomationRole = createIAMRole("AutomationRole");

// Administer Prod role for use in Prod environment
const EnvProdRole = createIAMRole("EnvProdRole");

Step 2: Create one EKS cluster. Validate cluster creation. Add the namespaces you need.

The Traditional-approach:

You go through the steps below to validate the cluster and k8s resource deployment based on your tool chain and your understanding of Kubernetes:

$ eksctl create cluster eks-nd-test
 
$ kubectl get no
NAME STATUS ROLES AGE VERSION
ip-192-168-41-125.us-east-2.compute.internal Ready <none> 11h v1.11.5
ip-192-168-5-250.us-east-2.compute.internal Ready <none> 11h v1.11.5
 
$ kubectl create -f automation-ns.yaml && kubectl create -f prod-ns.yaml
 
$ cat automation-ns.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: automation
  labels:
    name: automation

The Pulumi-approach:

You use our API docs and your source-code editor to autocomplete the default index.ts file.

/*
 * 2) Single step deployment of EKS cluster with the most important variables and a Simple Function to create namespaces
 * automation and prod
 */

const vpc = new awsx.ec2.Vpc("vpc", {});
const cluster = new eks.Cluster("eks-cluster", {
  vpcId : vpc.id,
  subnetIds : vpc.publicSubnetIds,
  instanceType : "t2.medium",
  nodeRootVolumeSize: 200,
  desiredCapacity : 1,
  maxSize : 2,
  minSize : 1,
  deployDashboard : false,
  vpcCniOptions : {
    warmIpTarget : 4,
  },
  roleMappings : [
    // Provides full administrator cluster access to the k8s cluster
    {
      groups : ["system:masters"],
      roleArn : clusterAdminRole.arn,
      username : "pulumi:admin-usr",
    },
    // Map IAM role arn "AutomationRoleArn" to the k8s user with name "automation-usr", e.g. gitlab CI
    {
      groups : ["pulumi:automation-grp"],
      roleArn : AutomationRole.arn,
      username : "pulumi:automation-usr",
    },
    // Map IAM role arn "EnvProdRoleArn" to the k8s user with name "prod-usr"
    {
      groups : ["pulumi:prod-grp"],
      roleArn : EnvProdRole.arn,
      username : "pulumi:prod-usr",
    },
  ],
});

export const clusterName = cluster.eksCluster.name;

function createNewNamespace(name: string): k8s.core.v1.Namespace {
  // Create new namespace
  return new k8s.core.v1.Namespace(name, { metadata: { name: name } }, { provider: cluster.provider });
}

// Declare namespaces automation and prod.
const automation = createNewNamespace("automation");
const prod = createNewNamespace("prod");

Step 3: Understand Kubernetes RBAC. Declare the Kubernetes objects on the EKS cluster.

The Kubernetes RBAC API declares four top-level types that can be defined as YAMLs syntaxes: a) Role - represents a set of additive rules within a namespace; b) RoleBinding - grants namespace-wide access to k8s subjects and resources; c) ClusterRole - represents a set of additive rules within the cluster; d) ClusterRoleBinding - grants cluster-wide access to k8s subjects and resources.

The Traditional-approach:

You define three k8s users with different privileges in your cluster and test them sequentially: User type1 called pulumi:admin-usr for users have cluster admin rights

 $ cat user1.yaml
 kind: ClusterRole
 apiVersion: rbac.authorization.k8s.io/v1
 metadata:
  name: ClusterAdminRole
  # no namespace needed
 rules:
 - apiGroups: ["*"]
  resources: ["*"]
  verbs: ["*"]
  
 ---
 kind: ClusterRoleBinding
 apiVersion: rbac.authorization.k8s.io/v1
 metadata:
   name: cluster-admin-binding
 subjects:
 - kind: User
  name: "pulumi:admin-usr"
  apiGroup: rbac.authorization.k8s.io
 roleRef:
  kind: ClusterRole
  name: ClusterAdminRole
  apiGroup: rbac.authorization.k8s.io`

User type2 called pulumi:automation-usr for users that have permissions to all k8s resources in namespace automation. An e.g would be your CI/CD pipeline

$ cat user2.yaml
 
kind: Role
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: AutomationRole
  namespace: automation
rules:
- apiGroups: ["*"]
  resources: ["*"]
  verbs: ["*"]
 
---
kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: automation-binding
  namespace: automation
subjects:
- kind: User
  name: "pulumi:automation-usr"
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: AutomationRole
  apiGroup: rbac.authorization.k8s.io

User type 3 called prod-usr for users that have read access to all k8s resources in the namespace prod

$ cat user3.yaml
 
kind: Role
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: EnvProdRole
  namespace: prod
rules:
- apiGroups: ["*"]
  resources: ["*"]
  verbs: ["get", "list", "watch"]
 
---
kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: env-prod-binding
  namespace: prod
subjects:
- kind: User
  name: "pulumi:prod-usr"
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: EnvProdRole
  apiGroup: rbac.authorization.k8s.io`
$ kubectl apply -f user1.yaml && kubectl apply -f user2.yaml && kubectl apply -f user3.yaml`
 
clusterrole.rbac.authorization.k8s.io/ClusterAdminRole created
clusterrolebinding.rbac.authorization.k8s.io/cluster-admin-binding created
role.rbac.authorization.k8s.io/AutomationRole created
rolebinding.rbac.authorization.k8s.io/automation created
role.rbac.authorization.k8s.io/EnvProdRole created
rolebinding.rbac.authorization.k8s.io/env-prod-binding created

The Pulumi-approach:

Update your index.ts file with more code as follows:

/*
 * 3) Single Step deployment of k8s RBAC configuration for user1, user2 and user3 per our example
 */

// Grant cluster admin access to all admins with k8s ClusterRole and ClusterRoleBinding
new k8s.rbac.v1.ClusterRole("clusterAdminRole", {
  metadata: {
    name: "clusterAdminRole",
  },
  rules: [{
    apiGroups: ["*"],
    resources: ["*"],
    verbs: ["*"],
  }]
}, {provider: cluster.provider});

new k8s.rbac.v1.ClusterRoleBinding("cluster-admin-binding", {
  metadata: {
    name: "cluster-admin-binding",
  },
  subjects: [{
     kind: "User",
     name: "pulumi:admin-usr",
  }],
  roleRef: {
    kind: "ClusterRole",
    name: "clusterAdminRole",
    apiGroup: "rbac.authorization.k8s.io",
  },
}, {provider: cluster.provider});

// User2 called automation-usr for users that have permissions to all k8s resources in the namespace automation
new k8s.rbac.v1.Role("AutomationRole", {
  metadata: {
    name: "AutomationRole",
    namespace: "automation",
  },
  rules: [{
    apiGroups: ["*"],
    resources: ["*"],
    verbs: ["*"],
  }]
}, {provider: cluster.provider});
  
new k8s.rbac.v1.RoleBinding("automation-binding", {
  metadata: {
    name: "automation-binding",
    namespace: "automation",
  },
  subjects: [{
     kind: "User",
     name: "pulumi:automation-usr",
     apiGroup: "rbac.authorization.k8s.io",
  }],
  roleRef: {
    kind: "Role",
    name: "AutomationRole",
    apiGroup: "rbac.authorization.k8s.io",
  },
}, {provider: cluster.provider});

// User3 called prod-usr for users that have read access to all k8s resources in the namespace env-prod
new k8s.rbac.v1.Role("EnvProdRole", {
  metadata: {
    name: "EnvProdRole",
    namespace: "prod",
  },
  rules: [{
    apiGroups: ["*"],
    resources: ["*"],
    verbs: ["get", "watch", "list"],
  }],
}, {provider: cluster.provider});
  
new k8s.rbac.v1.RoleBinding("env-prod-binding", {
  metadata: {
    name: "env-prod-binding",
    namespace: "prod",
  },
  subjects: [{
     kind: "User",
     name: "pulumi:prod-usr",
     apiGroup: "rbac.authorization.k8s.io",
    }],
  roleRef: {
    kind: "Role",
    name: "EnvProdRole",
    apiGroup: "rbac.authorization.k8s.io",
  },
}, {provider: cluster.provider});

export const kubeconfig = cluster.kubeconfig

Step 4: Update aws-iam-authenticator ConfigMap to map the IAM Roles to the Kubernetes usernames.

The Traditional-approach:

You get the three IAM role arns for clusterAdminRole, AutomationRole, EnvProdRole and update the configmap with k8s usernames pulumi:admin-usr, pulumi:automation-usr and pulumi:prod-usr.

mapRoles:
----
- groups:
  - system:masters
  rolearn: arn:aws:iam::XXXXXXXXXXXX:role/clusterAdminRole
  username: pulumi:admin-usr
- groups:
  rolearn: arn:aws:iam::XXXXXXXXXXXX:role/AutomationRole
  username: pulumi:automation-usr
- groups:
  rolearn: arn:aws:iam::XXXXXXXXXXXX:role/EnvProdRole
  username: pulumi:prod-usr
- groups:
  - system:bootstrappers
  - system:nodes
  rolearn: arn:aws:iam::XXXXXXXXXXXX:role/eksctl-eks-rbac-nd-test-nodegroup-NodeInstanceRole-NP542EG8JX8U
  username: system:node:`

The Pulumi-approach:

This step is not required as you have already updated the EKS ConfigMap at cluster creation time in STEP 2 using “RoleMappings”. Simply run pulumi up with the full index.ts file. Watch all your components come alive simultaneously. Setting up RBAC on one EKS cluster is a long convoluted sequential process that requires multiple validations along the way. Imagine the complexity involved when working with multiple tools for an environment that requires multiple groups with many users, namespaces, and clusters.

Testing the Pulumi approach worked

Make sure you run pulumi up with this index.ts file.

$ pulumi stack output kubeconfig | jq > kubeconfig.yaml
$ export KUBECONFIG = kubeconfig.yaml

Assume the IAM role AutomationRole with access to all Kubernetes resources in namespace automation and test if the permissions work.

 "users": [
    {
      "name": "aws",
      "user": {
        "exec": {
          "apiVersion": "client.authentication.k8s.io/v1alpha1",
          "args": [
            "token",
            "-i",
            "eks-cluster-eksCluster-196b0de",
            "-r",
            "arn:aws:iam::xxxxxxxxxxxx:role/AutomationRole"
          ],
          "command": "aws-iam-authenticator"
        }
      }
    }
  ]
}
 
$ kubectl get po --namespace=automation
No resources found.
 
$ kubectl get po --namespace=prod
Error from server (Forbidden): pods is forbidden: User "pulumi: automation-usr" cannot list resource "pods" in API group "" in the namespace "prod"

Upon assuming the IAM role AutomationRole which is mapped to Kubernernetes username pulumi:automation-usr in the EKS cluster configmap, you are only restricted to the resources and verbs allowed in the namespace “automation” and not in namespace “prod”.

Next Step

In this post, we discussed how setting up Kubernetes RBAC with Pulumi is simple, comprehensive, non-sequential and part of your everyday programming experience. You can find the complete pulumi code for our example and try it out yourself.

Pulumi is open source and free to use. For more examples, visit our GitHub examples page here. To learn more about Pulumi and how to manage Kubernetes through code, have a look at our “Get Started with Kubernetes” guide.

Testing Your Infrastructure as Code with Pulumi

Joe Duffy — Wed, 17 Apr 2019 00:00:00 +0000

Some parts of this blog post are out-of-date. Please refer to our Testing Guide for the updated overview and tutorials.

Using Pulumi and general purpose languages for infrastructure as code comes with many benefits: leveraging existing skills and knowledge, eliminating boilerplate through abstraction, and using the same ecosystem of tools like IDEs and linters that your team already knows and loves. In general, these are all attributes of software engineering, which not only make us more productive, but also improve the quality of our code. It’s only natural, therefore, that using general purpose languages unlocks another important software engineering practice: testing.

In this article, we will see the many ways in which Pulumi lets us test our infrastructure as code.

Why Test Your Infrastructure?

Before jumping into the details, it’s worth asking: Why test your infrastructure, anyway? There are many reasons to do this, however here are a few examples:

Unit testing individual functions or pieces of logic in your program
Ensuring that the program’s desired infrastructure state meets certain constraints
Catching common mistakes, like forgetting to encrypt your storage buckets, or exposing virtual machines unprotected to the open Internet
Ensuring that the provisioned infrastructure has certain desired attributes
Doing runtime testing of the application logic that is running inside of your compute infrastructure, to ensure that it is healthy after your infrastructure has been provisioned

As we see, there’s a broad spectrum of infrastructure testing options available. Pulumi has mechanisms available for testing at each point along this spectrum. Let’s dig in and see how.

Unit Testing

Pulumi programs are authored in a general purpose language like JavaScript, Python, TypeScript, or Go. The full power of each language is available, including access to tools and libraries for that runtime, including testing frameworks. Pulumi is also multi-cloud, meaning the full underlying platform for each cloud is available too, and therefore available for testing.

(Despite being multi-language and multi-cloud, for the purposes of this article let’s assume we are using JavaScript, with Mocha for testing, and targeting AWS. Python unittest, Go’s test framework, or any of your favorite unit test frameworks in your language of choice would do, and of course Pulumi works great with Azure, Google Cloud, and Kubernetes, among others.)

As we’ve seen, there are several reasons you may want to test your infrastructure code. One of them is basic unit testing. Because your code may have functions – say, to compute CIDR blocks, dynamically compute names and tags, etc. – you probably want to test them. Doing this is the same as writing ordinary unit tests against any program in your language as choice.

Going one step further, you may want to test the way your program allocates resources. To illustrate, let’s imagine we want to create a simple EC2-based webserver, but want to ensure:

Instances have a Name tag.
Instances must not use an inline userData script – we must use an AMI (image).
Instances must not have SSH open to the Internet.

Our running example is loosely based on our aws-js-webserver example:

index.js:

let aws = require("@pulumi/aws");

let group = new aws.ec2.SecurityGroup("web-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"] },
    ],
});

let userData =
`#!/bin/bash echo "Hello, World!" > index.html nohup python -m SimpleHTTPServer 80 &`;

let server = new aws.ec2.Instance("web-server-www", {
    instanceType: "t2.micro",
    securityGroups: [ group.name ], // reference the group object above
    ami: "ami-c55673a0" // AMI for us-east-2 (Ohio),
    userData: userData // start a simple web server
});

exports.group = group;
exports.server = server;
exports.publicIp = server.publicIp;
exports.publicHostName = server.publicDns;

This is a basic Pulumi program: it simply allocates an EC2 security group and instance. Notice, however, that we are violating all three of the rules stated above – let’s write some tests!

Writing the Tests

The overall structure and scaffolding of our tests will look like any ordinary Mocha testing:

ec2tests.js

let assert = require("assert");
let mocha = require("mocha");
let pulumi = require("@pulumi/pulumi");
let infra = require("./index");

describe("Infrastructure", function() {
    let server = infra.server;
    describe("#server", function() {
 // TODO(check 1): Instances have a Name tag.
 // TODO(check 2): Instances must not use an inline userData script.
    });
    let group = infra.group;
    describe("#group", function() {
 // TODO(check 3): Instances must not have SSH open to the Internet.
    });
});

Now let’s implement our first test: ensuring that instances have a Name tag. To verify this we simply need to grab hold of the EC2 instance object, and check the relevant tags property:

// check 1: Instances have a Name tag.
it("must have a name tag", function(done) {
 pulumi.all([server.urn, server.tags]).apply(([urn, tags]) => {
     if (!tags || !tags["Name"]) {
     done(new Error(`Missing a name tag on server ${urn}`));
     } else {
      done();
     }
    });
});

This looks like a normal test, with a few noteworthy pieces:

Since we’re querying resource state before we’ve done a deployment, our tests are always effectively running in “plan” (or “preview”) mode. Thus, there are many properties whose values will simply not resolve yet or will be undefined. This includes any output properties computed by your cloud provider. That’s fine for these tests – we’re checking for valid inputs anyway. We’ll revisit this later when it comes to integration testing.
Because all Pulumi resource properties are “outputs” – since many of them are computed asynchronously – we need to use the apply method to get access to the values. This is a lot like promises and the then function.
Because we are using multiple properties, mostly just so we can show the resource URN in the error message, we need to use the pulumi.all function to join all of them.
Finally, since these outputs are resolved asynchronously, we need to use Mocha’s built-in asynchronous test capability, with the done callback, or by returning a promise.

After we’ve gotten through that setup, we get access to the raw inputs as plain JavaScript values. The tags property is a map, so we just make sure it is (1) not falsey, and (2) not missing an entry for the Name key in the map. This is very basic, but we can check anything!

Now let’s write our second check. It’s even easier:

// check 2: Instances must not use an inline userData script.
 it("must not use userData (use an AMI instead)", function(done) {
 pulumi.all([server.urn, server.userData]).apply(([urn, userData]) => {
 if (userData) {
 done(new Error(`Illegal use of userData on server ${urn}`));
 } else {
 done();
 }
    });
});

And finally, let’s write our third check. It’s a bit more complex because we’re searching for ingress rules associated with a security group – of which there may be many – and CIDR blocks within those ingress rules – of which there may also be many. But it’s still easy:

// check 3: Instances must not have SSH open to the Internet.
it("must not open port 22 (SSH) to the Internet", function(done) {
 pulumi.all([ group.urn, group.ingress ]).apply(([ urn, ingress ]) => {
 if (ingress.find(rule =>
 rule.fromPort == 22 && rule.cidrBlocks.find(block => block === "0.0.0.0/0"))) {
     done(new Error(`Illegal SSH port 22 open to the Internet (CIDR 0.0.0.0/0) on group ${urn}`));
 } else {
     done();
 }
    });
});

That’s it – now let’s actually run the tests!

Running the Tests

For the most part, we can run the tests in the usual way in your test framework of choice. There is one thing specific to Pulumi we need to cover first, however.

Usually you run your Pulumi programs with the pulumi CLI. That configures the language runtime, monitors execution from the engine so that resource operations can be recorded and turned into a plan, and so on. There is one problem, however: When running under the watchful eye of your test framework, this connection to the CLI, and Pulumi’s engine, will not exist.

To work around this problem, we simply have to mock three pieces of information:

Your project name, which can be supplied with the PULUMI_NODEJS_PROJECT environment variable (or more generally PULUMI_<LANGUAGE>_PROJECT in other languages).
Your stack name, which can be supplied with the PULUMI_NODEJS_STACK environment variable (or more generally PULUMI_<LANGUAGE>_STACK in other languages).
Your stack configuration variables. These can be supplied using the PULUMI_CONFIG environment variable, and its format is a JSON map of configuration key/value pairs.

The program will emit some warning messages indicating the connection to the CLI/engine is not available at runtime. This is important to know, because your program won’t actually be deploying anything – which can come as a surprise if that’s not what you meant to do! To tell Pulumi that’s what you intended, you can set PULUMI_TEST_MODE to true.

Imagine we want a project name of my-ws, stack name of dev, and AWS region of us-west-2. The command line to run your Mocha tests would therefore be:

$ PULUMI_TEST_MODE=true \
 PULUMI_NODEJS_STACK="my-ws" \
 PULUMI_NODEJS_PROJECT="dev" \
 PULUMI_CONFIG='{ "aws:region": "us-west-2" }' \
 mocha tests.js

Running this will tell us that we have three failing tests, as we had hoped!

 Infrastructure
    #server
1) must have a name tag      2) must not use userData (use an AMI instead)
    #group
3) must not open port 22 (SSH) to the Internet
  0 passing (17ms)
  3 failing
 1) Infrastructure
       #server
 must have a name tag:
Error: Missing a name tag on server
urn:pulumi:my-ws::my-dev::aws:ec2/instance:Instance::web-server-www
 2) Infrastructure
       #server
 must not use userData (use an AMI instead):
Error: Illegal use of userData on server
urn:pulumi:my-ws::my-dev::aws:ec2/instance:Instance::web-server-www
 3) Infrastructure
       #group
 must not open port 22 (SSH) to the Internet:
Error: Illegal SSH port 22 open to the Internet (CIDR 0.0.0.0/0) on group

Let’s fix our program to comply:

"use strict";

let aws = require("@pulumi/aws");

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

let server = new aws.ec2.Instance("web-server-www", {
    tags: { "Name": "web-server-www" },
    instanceType: "t2.micro",
    securityGroups: [ group.name ], // reference the group object above
    ami: "ami-c55673a0" // AMI for us-east-2 (Ohio),
});

exports.group = group;
exports.server = server;
exports.publicIp = server.publicIp;
exports.publicHostName = server.publicDns;

And then rerun our tests:

 Infrastructure
    #server
      ✓ must have a name tag
      ✓ must not use userData (use an AMI instead)
    #group
      ✓ must not open port 22 (SSH) to the Internet
 3 passing (16ms)

They all passed – huzzah! ✓✓✓

Deployment Testing

This style of testing is powerful and lets us do white box testing of the innards of how our infrastructure code works. This style of testing is somewhat limited in what we can check, however. The tests run on an in-memory representation of Pulumi’s deployment plan – before actually performing the deployment – and so cannot test anything the deployment itself. For that, Pulumi has an integration test framework. The two approaches work great together!

Pulumi’s integration test framework is written in Go and is how we test much of our internal code. If the earlier unit test approach took more of a white box testing approach, the integration test framework is very much black box. (There are also options for thorough internals-oriented testing.) This framework has been built to take a directory containing a full Pulumi program and drive various lifecycle operations against it – such as deploying a new stack from scratch, updating it with variations, and tearing it down afterwards, potentially multiple times. We run these in checkin suites, on a recurring basis (such as nightly), and as stress tests.

(We have an open work item which will bring similar integration testing capabilities to each native language SDK. You can use the Go integration test framework no matter the language your Pulumi program is written in, however.)

By running a program through this integration test framework, you can ensure:

Your project’s code is syntactically well formed and runs without errors.
Your stack’s configuration and secrets settings work and are interpreted correctly.
Your project can be successfully deployed to your cloud provider of choice.
Your project can be successfully updated from its starting state to N other states.
Your project can be successfully destroyed and removed from your cloud provider.

As we will see soon, you can also leverage this framework to perform runtime validation.

A Basic Integration Test

To see this in action, we’ll look from the pulumi/examples repo, since our team and community here at Pulumi use that to validate our own examples in pull requests, checkins, and nightlies.

The following is a simplified test of our example that provisions an S3 bucket and some objects in Pulumi:

example_test.go:

package test

import (
    "os"
    "path"
    "testing"

    "github.com/pulumi/pulumi/pkg/testing/integration"
)

func TestExamples(t *testing.T) {
    awsRegion := os.Getenv("AWS_REGION")
    if awsRegion == "" {
 awsRegion = "us-west-1"
    }
    cwd, _ := os.Getwd()
    integration.ProgramTest(t, &integration.ProgramTestOptions{
 Quick: true,
 SkipRefresh: true,
 Dir: path.Join(cwd, "..", "..", "aws-js-s3-folder"),
 Config: map[string]string{
     "aws:region": awsRegion,
 },
    })
}

This test runs through a basic lifecycle of stack creation, updating, and destruction, for the aws-js-s3-folder example. It takes about a minute or so to report success:

$ go test .
PASS
ok ... 43.993s

There are many, many options to control the behavior of these tests. For a full set of options, see the ProgramTestOptions data structure. For instance, you can configure a Jaeger endpoint for tracing (Tracing), tell the harness to expect failure for negative testing (ExpectFailure), apply a series of “edits” to the program for a sequence of update state transitions (EditDirs), and more. Let’s see how to use these to do validate that we deployed what we expected.

Validating the Shape of Resources

All of the above integration ensures that our program “works” – as in, it does not crash. But what if we want to validate properties of the resulting stack? For example, that certain kinds of resources did (or did not) get provisioned, and that they have certain attributes.

The ExtraRuntimeValidation option for ProgramTestOptions allows us to look at the post-deployment state that Pulumi has captured, so that we can do extra validation on it. This includes a full snapshot of the resulting stack’s state, including configuration, exported outputs, all resources and their property values, and all inter-resource dependencies.

To see a basic example of this, let’s check that our program creates a single S3 Bucket:

integration.ProgramTest(t, &integration.ProgramTestOptions{
 // as before...
 ExtraRuntimeValidation: func(t *testing.T, stack integration.RuntimeValidationStackInfo) {
     var foundBuckets int
     for _, res := range stack.Deployment.Resources {
 if res.Type == "aws:s3/bucket:Bucket" {
      foundBuckets++
 }
     }
     assert.Equal(t, 1, foundBuckets, "Expected to find a single AWS S3 Bucket")
 },
})

Now when we run go test, it will not only run through the battery of lifecycle tests but will also, after successfully standing up the stack, perform the extra validation against the resulting state.

Runtime Testing

All of the testing thus far has been exclusively about deployment behavior and the Pulumi resource model. What if you want to test that your provisioned infrastructure is actually working, however? For example, that our VM is alive, our S3 bucket contains what we expect, and so on.

You may have already guessed how to accomplish some of this: the ExtraRuntimeValidation option for ProgramTestOptions is the perfect opportunity to do this. At this point, you are running an arbitrary Go test, with access to the full state of your program’s resources. This state includes information such as VM IP addresses, URLs, and everything you need to actually interact with your resulting cloud applications and infrastructure to perform verification.

For instance, our test program above exports the bucket’s websiteEndpoint property, as the stack output named websiteUrl, which is a full URL that we can use to fetch the bucket’s configured index document. Although we could just as well have dug through the state file to find the bucket and read this property directly, many times our stacks will export useful properties like this that we can use conveniently for verification:

    integration.ProgramTest(t, &integration.ProgramTestOptions{
     // as before ...
 ExtraRuntimeValidation: func(t *testing.T, stack integration.RuntimeValidationStackInfo) {
     url := "http://" + stack.Outputs["websiteUrl"].(string)
     resp, err := http.Get(url)
     if !assert.NoError(t, err) {
 return
     }
     if !assert.Equal(t, 200, resp.StatusCode) {
 return
     }
     defer resp.Body.Close()
     body, err := ioutil.ReadAll(resp.Body)
     if !assert.NoError(t, err) {
 return
     }
     assert.Contains(t, string(body), "Hello, Pulumi!")
 },
})

Like our previous runtime validation checks, this will run in the harness right after the stack is stood up, all in response to a simple go test invocation. This just scratches the surface of what’s possible – anything you can write in code using Go’s test capabilities is within reach!

Continuous Infrastructure Integration

It’s wonderful to be able to easily run these on demand, on a laptop, when you’re iterating on infrastructure changes and want to verify them before submitting for code review. But we and many of our customers run infrastructure testing at various points in the development lifecycle:

In each pull request opened, to validate before allowing it to be merged.
In response to each commit, to double check it was merged correctly.
On a recurring basis, such as nighty or even weekly for extended testing.
As part of more exotic and thorough test programs, such as performance or stress testing, which typically run over a longer period of time, execute many things in parallel, and/or deploy the same program multiple times.

For each of these, Pulumi supports integration with your favorite continuous integration system. This gives you similar continuous integration testing coverage for your infrastructure as you might already enjoy for your application software or in other programming domains.

Pulumi supports your existing CI systems. Here are a few of those supported:

Please refer to the Continuous Delivery documentation for a more comprehensive guide.

Ephemeral Environments

A very powerful capability this unlocks is the ability to spin up ephemeral environments solely for purposes of acceptance testing. Pulumi’s concept of projects and stacks is designed to make it very easy to stand up entirely isolated and independent environments, and to tear them down, all in either a few easy CLI gestures, or by using the integration testing framework.

If you are using GitHub, Pulumi offers a GitHub App that helps to glue together your Pull Request workflow with this sort of acceptance testing run inside of your CI pipelines. Simply install the App into your GitHub repos, and Pulumi in your CI, and your Pull Requests will light up with infrastructure previews, updates, and test results seamlessly:

By leveraging Pulumi for your core acceptance test workflow, you’ll unlock new automation capabilities that improve your team’s productivity and confidence in the quality of changes.

In Summary

In this post, we saw that by using general purpose programming languages, we unlock many software engineering practices we’ve benefited from in our application development. This includes unit testing, integration testing, and even the intersection of both to do extensive runtime testing. It’s easy to run these on demand and harness them in your CI system of choice.

Pulumi is open source, free to use, and works with your favorite languages and clouds – give it a try today!

From Terraform to Infrastructure as Software

Pat Gavlin — Fri, 02 Nov 2018 00:00:00 +0000

Here at Pulumi, we love programming the cloud using infrastructure as code. From the project’s outset, we’ve been inspired by technologies like Terraform, AWS CloudFormation, and Helm, and in fact leverage the Terraform Providers ecosystem, to support a broad range of clouds, including AWS, Azure, and Google Cloud.

Just recently, we extended this with first class support for Kubernetes. Pulumi delivers the same infrastructure as code workflows only using general purpose languages like JavaScript, TypeScript, Python, and Go, extending robust infrastructure provisioning with abstraction and reuse, highly productive tooling, and access to all the other things we already know and love about programming languages.

In this article, we will convert existing Terraform configuration to Pulumi TypeScript. By doing so, we’ll see how using general purpose programming languages can help you create simpler, more flexible infrastructure as code, with greater productivity and less repetition. The infrastructure we’ll be working with describes a load-balanced web server hosted by an AWS EC2 instance per availability zone with an option to allow SSH access. Of course, these same benefits would also accrue were we to target Azure, Google Cloud, or Kubernetes instead.

Starting from Terraform Configuration

The Terraform configuration we’ll be starting with is below. This configuration accepts a list of AZs and an optional public key as inputs and produces a (possibly empty) list of the web servers’ public IP addresses and the URL of the load-balanced web site as outputs. When a public key is provided, this configuration will enable SSH access to the virtual machines that serve the web site.

Let’s walk the example one step at a time – feel free to skip ahead if you’re a Terraform expert and just want to see how Pulumi is different.

First, we declare that availability_zones and public_key are parameterizable inputs:

variable "availability_zones" {}
variable "public_key" {
default = ""
}

And then we look up the latest AWS AMI for Ubuntu Trusty in our current region. This is what our web server will run when we get around to provisioning it later:

data "aws_ami" "ubuntu" {
 most_recent = true
 filter {
   name   = "name"
   values = ["ubuntu/images/hvm-ssd/ubuntu-trusty-14.04-amd64-server-*"]
 }
 filter {
   name   = "virtualization-type"
   values = ["hvm"]
 }
 owners = ["099720109477"] # Canonical
}

Next, we’ll create security groups that allow HTTP ingress on port 80 and, if a public key is available, SSH over port 22, in addition to allowing outbound Internet access. Notice that we are using the count property for the SSH rule to enable it conditionally:

resource "aws_security_group" "default" {
name_prefix = "example_sg"
}
resource "aws_security_group_rule" "allow_http" {
type = "ingress"
from_port = 80
to_port = 80
protocol = "tcp"
cidr_blocks = ["0.0.0.0/0"]
security_group_id = "${aws_security_group.default.id}"
}
resource "aws_security_group_rule" "allow_all_outbound" {
type = "egress"
from_port = 0
to_port = 0
protocol = "-1"
cidr_blocks = ["0.0.0.0/0"]
security_group_id = "${aws_security_group.default.id}"
}
resource "aws_security_group_rule" "allow_ssh" {
 count = "${var.public_key == "" ? 0 : 1}"
 type = "ingress"
 from_port = 22
 to_port = 22
 protocol = "tcp"
 cidr_blocks = ["0.0.0.0/0"]
 security_group_id = "${aws_security_group.default.id}"
}

Now let’s actually create the web servers. This is where things get a little awkward in a DSL, because we want to conditionally attach the key_name, based on whether SSH access is enabled. This requires that we duplicate some configuration for the key and no-key code paths, in addition to splitting, transforming, and indexing into our list of AZs:

 resource "aws_key_pair" "default" {
 count = "${var.public_key == "" ? 0 : 1}"
 key_name_prefix = "default"
 public_key = "${var.public_key}"
}
resource "aws_instance" "web-server-key" {
 count = "${var.public_key == "" ? 0 : length(split(",", var.availability_zones))}"
 ami = "${data.aws_ami.ubuntu.id}"
 instance_type = "t2.micro"
 availability_zone = "${element(split(",", var.availability_zones), count.index)}"
 user_data = "${file("userdata.sh")}"
 security_groups = ["${aws_security_group.default.name}"]
 key_name = "${aws_key_pair.default.0.key_name}"
}
resource "aws_instance" "web-server-nokey" {
 count = "${var.public_key == "" ? length(split(",", var.availability_zones)) : 0}"
 ami = "${data.aws_ami.ubuntu.id}"
 instance_type = "t2.micro"
 availability_zone = "${element(split(",", var.availability_zones), count.index)}"
 user_data = "${file("userdata.sh")}"
 security_groups = ["${aws_security_group.default.name}"]
}

After creating the web servers, we will create and attach an ELB, so that traffic is spread across the AZs. This also requires the same conditional duplication for key and no-key configurations:

resource "aws_elb" "elb" {
name_prefix = "webelb"
availability_zones = ["${split(",", var.availability_zones)}"]
listener {
instance_port = 80
instance_protocol = "http"
lb_port = 80
lb_protocol = "http"
}
health_check {
healthy_threshold = 2
unhealthy_threshold = 2
timeout = 3
target = "HTTP:80/"
interval = 30
}
}
resource "aws_elb_attachment" "web-server-key" {
count = "${var.public_key == "" ? 0 : length(split(",", var.availability_zones))}"
elb = "${aws_elb.elb.id}"
instance = "${element(aws_instance.web-server-key.*.id, count.index)}"
}
resource "aws_elb_attachment" "web-server-nokey" {
count = "${var.public_key == "" ? length(split(",", var.availability_zones)) : 0}"
elb = "${aws_elb.elb.id}"
instance = "${element(aws_instance.web-server-nokey.*.id, count.index)}"
}

Finally, we’ll export the public instance IPs for SSH access (if enabled) and the ELB URL:

output "public_ips" {
 value = "${aws_instance.web-server-key.*.public_ip}"
}
output "url" {
 value = "http://${aws_elb.elb.dns_name}"
}

And that’s it. This program provisions an EC2 VM per AZ in your region of choice, behind a load balancer, with conditional SSH enablement.The full code is available here if you’d like to see it in one place.

Migrating to a General Purpose Language

Now let’s see how to migrate this program to using a general purpose language. There are several opportunities to simplify the program – most immediately apparent, using familiar if statements instead of the the awkward conditionals that use count variables.

We could just go ahead and convert the program by hand, however the tf2pulumi tool was designed to take a Terraform HCL program as input and perform the entire translation automatically for you. This is a great place to get started – and from there we can then refactor the resulting program gradually to leverage languages better.

As of Pulumi CLI v3.71.0, tf2pulumi has been replaced with pulumi convert --from terraform. Converting Full Terraform Programs to Pulumi blog has more details.

The first step is to create a Pulumi project. Download Pulumi here, and then run:

$ pulumi new aws-typescript
-n webservers -d "Pulumi Web Servers" -g -f

Run this from wherever your Terraform program resides. This will initialize and scaffold a minimal Pulumi TypeScript program targeting AWS in the pulumi subdirectory.

We’ll then install tf2pulumi, and run it, to generate the Pulumi TypeScript program in index.ts:

$ tf2pulumi

The full program created by this command can be found here. Notice that it looks structurally very similar to the Terraform HCL program above, except that it’s written in TypeScript instead. Even this rote translation has benefits – for example, open it in your favorite editor, and you’ll notice you get syntax highlighting, statement completion, and integrated documentation. But we’ll soon see that once we have this code in our favorite language, we can refactor it to leverage familiar programming languages more idiomatically, reducing a lot of boilerplate.

After the conversion is complete, we can create, configure, and update a Pulumi stack to create the resources described by the generated Pulumi program:

$ cd pulumi
$ npm install
$ pulumi stack init webservers-prod
$ pulumi config set aws:region us-west-2
$ pulumi config set availabilityZones "us-west-2a,us-west-2b,us-west-2c"
$ pulumi up

A Pulumi stack is an environment that can be configured and deployed to independently of all other stacks. Here we’ve created webservers-prod and set it to deploy into the us-west-2a, us-west-2b, and us-west-2c availability zones in AWS’s us-west-2 region. pulumi up will then show you a plan and then let you confirm it to deploy your resources:

After selecting “yes”, the update will proceed with interactive status updates:

Leveraging Programming Languages

This is great – we now have a working Pulumi program. Let’s now go about simplifying the generated code so that it is easier to read, understand, and maintain. We’ll only scratch the surface in this post, as many of the real benefits shine when you go beyond a single program and use reusable constructs like functions, classes, and packages, to cut down on copy and paste. But even some of the syntactic transformations we’ll make can provide a real boost to productivity.

First, notice that our package dependencies are just NPM packages. The full ecosystem of our language’s native package manager is available to us:

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

The first order of business is to place the list of configured availability zones into a local variable:

const availabilityZones = config.require("availabilityZones").split(",");

Because Pulumi programs are ordinary programs, we can use variables in the usual ways. Notice that we’ve not only defined a variable, but also split the string, so that we don’t need to do it on every usage within the file, using the standard JavaScript split function.

Terraform data sources are represented as function calls in our program. So, to fetch the Ubuntu AMI, we simply call the getAmi function, passing in the filters as parameters to it:

const ubuntuAmi = aws.getAmi({
 filters: [
 { name: "name", values: ["ubuntu/images/hvm-ssd/ubuntu-trusty-14.04-amd64-server-*"] },
 { name: "virtualization-type", values: ["hvm"] },
 ],
 mostRecent: true,
 owners: ["099720109477"], // Canonical
});

We already saw how the use of variables can save us from repeating ourselves over and over again, and again, we can use this to avoid repeating the 0.0.0.0/0 CIDR block everywhere:

const anyCidr = ["0.0.0.0/0"];
const webServerSg = new aws.ec2.SecurityGroup("default", {
 egress: [{ cidrBlocks: anyCidr, fromPort: 0, protocol: "-1", toPort: 0 }],
 ingress: [{ cidrBlocks: anyCidr, fromPort: 80, protocol: "tcp", toPort: 80 }],
});

Now we can change how we conditionally create the web server instances. This is where we’ll start to see the big wins, because we can use any of the familiar programming language control constructs, including for loops, case statements, if blocks, function calls, and even higher order list functions like map and filter.

In order to conditionally create a resource in Terraform, we had to set its count to either 0 or the desired AZ count. However, this affects any resources that depend on the conditional resource: the dependent resources either become conditional themselves or require complex interpolation expressions in order to ensure that the configuration does not reference any undefined properties. In our original Terraform configuration, the conditional creation of an AWS Key Pair forces us to declare our web servers twice: once with the key pair and once without.

resource "aws_key_pair" "default" {
count = "${var.public_key == "" ? 0 : 1}"
…
resource "aws_instance" "web-server-key" {
count = "${var.public_key == "" ? 0 : length(split(",", var.availability_zones))}"
…
resource "aws_elb_attachment" "web-server-key" {
count = "${var.public_key == "" ? 0 : length(split(",", var.availability_zones))}"
…
resource "aws_instance" "web-server-nokey" {
count = "${var.public_key == "" ? length(split(",", var.availability_zones)) : 0}"
…
resource "aws_elb_attachment" "web-server-nokey" {
count = "${var.public_key == "" ? length(split(",", var.availability_zones)) : 0}"
…

This is rather cumbersome. The syntactic transformation performed by tf2pulumi preserved this same structure to ensure the semantics of translation are identical, but we can now go back and clean it up considerably.

First, to conditionally allocate an EC2 KeyPair and to open port 22, we use an if statement:

let keyName: pulumi.Output<string> | undefined;
if (publicKey) {
 keyName = new aws.ec2.KeyPair("default", { publicKey }).id;
 new aws.ec2.SecurityGroupRule("allow_ssh", {
 type: "ingress",
 cidrBlocks: anyCidr,
 fromPort: 22,
 toPort: 22,
 protocol: "tcp",
 securityGroupId: webServerSg.id,
 });
}

The use of conditionals just works and interacts with planning just as you might expect, so that we always see the result of the conditional evaluation before we’ve decided to deploy anything.

Another subtle advantage is that we can just pass the webServerSg.id property – Pulumi understands the resource DAG, and the use of this property automatically forms an edge.

Now let’s create our web servers. We might use a for loop for this, and append each one to an array, however it’s just as easy to use the JavaScript map function to do this more declaratively:

const webServers: aws.ec2.Instance[] = availabilityZones.map(az =>
 new aws.ec2.Instance(`web-server-key-${az}`, {
 ami: ubuntuAmi.then(ami => ami.id),
 associatePublicIpAddress: publicKey !== "",
 availabilityZone: az,
 instanceType: "t2.micro",
 securityGroups: [ webServerSg.name ],
 userData: fs.readFileSync("userdata.sh", "utf-8"),
 keyName: keyName,
 }),
);

Interestingly, we’ve passed keyName to the constructor here, even though it might not have been defined (the JavaScript default value of undefined). Pulumi understands that this means “the absence of a value”, which is how we were able to simplify the web server provisioning so greatly. We also read in the userdata.sh file using standard JavaScript I/O functionality.

Now that we’ve simplified our configuration such that the web servers are declared once, we can simplify their interaction with the load balancer. We can just create the ELB last and pass it a list of all of our instances. We can also improve the reliability of configuration by ensuring that the ELB is associated with each availability zone in which we’ve created a web server:

const webServerElb = new aws.elasticloadbalancing.LoadBalancer("elb", {
 availabilityZones: webServers.map(instance => instance.availabilityZone),
 instances: webServers.map(instance => instance.id),
 healthCheck: {
 healthyThreshold: 2,
 interval: 30,
 target: "HTTP:80/",
 timeout: 3,
 unhealthyThreshold: 2,
 },
 listeners: [{
 instancePort: 80,
 instanceProtocol: "http",
 lbPort: 80,
 lbProtocol: "http",
 }],
});

Finally, the way we express outputs is by using standard JavaScript module exports:

export const publicIps = webServers.map(v => v.publicIp);
export const url = webServerElb.dnsName.apply(hostname => `http://${hostname}`);

And that’s it. After doing this refactoring, you can simply run pulumi up, and it will show you any diffs compared to your previous deployment, which you can choose to accept and deploy. The full code is available here.

Next Steps

In this post, we’ve applied general purpose programming languages to infrastructure as code to achieve more expressive and reusable programs, simplify our infrastructure’s readability and maintainability, and deliver a heightened level of productivity. Pulumi is open source and free to use – give it a try today!

Lambdas as Lambdas: The magic of simple serverless Functions

Cyrus Najmabadi — Wed, 10 Oct 2018 00:00:00 +0000

Pulumi’s approach to infrastructure as code uses familiar languages instead of YAML or DSLs. One major advantage of this approach is that AWS Lambdas, Azure Functions, Google Cloud Functions, et al. can just be real lambdas in your favorite language, offering a flexible and simple path to serverless. Such functions behave as normal functions, allowing you to treat serverless code as part of your application instead of separate “infrastructure” that needs to be configured, managed, and versioned manually. In this post, we’ll examine this capability in JavaScript, which is already very function- and callback-oriented, making serverless feel like a natural extension of the language we already know and love.

While Functions as a Service (FaaS) systems have become more popular, getting up and running can still feel overly complex compared to normal application development. FaaS offerings today divide the development experience between “infrastructure” – doing all the work to configure the Lambda runtime itself (i.e. how much memory to use, what environment variables should be present, etc.) – and writing and maintaining the code that will execute in the function itself when triggered. Most developers just want to focus on the latter, write some code, and have it work.

For AWS Lambda, for example, the code itself needs to written and packaged up with all its dependencies into a single zip-file, stored as a blob that is then placed in AWS S3. This blob is then referenced by Lambda so that it can be loaded on-demand when necessary. Updating just a single character of this code, like fixing a bug, then requires fully repackaging and re-uploading everything. Compounding all of that, this code is necessary independent of any other pieces of your application. If the code for the Lambda needs to read or write to an S3 bucket, publish to an AWS SNS topic, etc., it will need to be manually configured to have that bucket’s information passed to it, often using out of band in environment variables. These same issues also apply when creating FunctionApps using Node.js on Azure.

At Pulumi, we thought there could be a better way to do this. Why have to jump out of your application code just to create another bit of configuration (in YAML or JSON) just to run your application? Put simply, we wanted developers to write event-driven code, in their favorite language and in their favorite IDE, and simply hit “deploy” when done.

Magic Functions

From a desire to do better here, the “closure serialized function” was born. However, “closure serialized function” is a geeky mouthful, so I like just calling them “magic functions.” Our team is comprised of cloud, language, and runtime geeks alike, so we figured out a way to hook into the language runtimes to just make lambdas as lambdas work.

Before diving more deeply into how magic functions work, let’s take a look at how they look in action:

// Example simplified to not get too bogged down :)
const sharp = require("sharp");
const videoBucket = new aws.s3.Bucket("videos");
const videoTopic = new cloud.Topic("videoTopic");
videoBucket.onObjectCreated("onNewVideo", async (event) => {
for (const record of event.Records) {
const dimensions = computeDimensions(record.s3.object.key);
videoTopic.publish({ s3ObjectKey: record.s3.object.key, time: record.eventTime });
}
});
function computeDimensions(objectKey: string): { height: number, width: number } {
/* simplified */
const metadata = await sharp(...);
return { height: metadata.height, width: metadata.width };
}
videoTopic.subscribe("compressVideo", async (event) => {
const { s3ObjectKey, time } = event;
// actually compress video.
});
videoTopic.subscribe("createThumbnail", async (event) => {
const { s3ObjectKey, time } = event;
// actually create thumbnail.
});

Let’s still walk through it to see what’s happening. It can be a little subtle because we are mixing deployment-time code – code that declares infrastructure as code resources – and *runtime *code – application code that runs as a function.

First, we’re just defining two simple resources: 1) an s3.Bucket, where we expect new video files to be uploaded to, and 2) a cloud.Topic that will inform interested parties when new videos are uploaded. (The full surface area of AWS is available in the aws package, and the cloud package offers multi-cloud abstractions that work at a higher level of abstraction.) Right after defining the resources, we start creating our first FaaS resources. videoBucket has an onObjectCreated event subscription function that will fire when new objects appear, and we invoke it with a real JavaScript (or TypeScript) arrow-function defining the code that will execute in an AWS Lambda at runtime.

Not So Fast…

This code is pretty magical in a few ways. To see how it’s magic, let’s consider a fairly naive way to create a Lambda for this onObjectCreated event handler function – something we need to do by hand with FaaS solutions today. Imagine we took the raw source text of this arrow-function by toStringing it and using that as the text of the Lambda code:

// index.js
module.exports = async (event) => {
foreach (var record in event.Records) {
const dimensions = computeDimensions(record.s3.object.key);
videoTopic.publish({ s3ObjectKey: record.s3.object.key, time: record.eventTime });
}
};

Now, the above translation could have worked for an extremely basic function, but totally breaks down here for several reasons. First, computeDimensions isn’t included, which will make this immediately fail if ever called. Second, if computeDimensions was included, it wouldn’t work unless the sharp module was properly imported for it. Third, even if the module was imported in the code, the actual NPM package would have to be available along with the code in the cloud. Fourth, if that module was properly required, and the package was properly included, the code is both referencing videoTopic (a resource defined when the application originally ran), and it is invoking a helper method on it. Remember, this code is going to be executing at cloud runtime, not at the time when Pulumi is actually executing the application on your developer machine, and actually doing things like running the const videoTopic = new cloud.Topic("videoTopic") code.

To summarize, we have quickly realized, we can’t just analyze everything locally to figure out what has to be included, instead the entire transitive closure must be considered – a task usually left up to FaaS developers to perform manually! This coupled with the manual configuration using YAML can lead to plenty a headache.

Compilers to the Rescue

Despite all those issues, Pulumi is able to make that original application code work and it is able to magically effectively translate the above into a working Lambda. The real secret sauce here is that, by leveraging familiar languages, we can stand on the shoulders of all the great compiler work underpinning them.

So let’s dig in – how does this all really work?

(Note that, if you want some of the more nitty gritty details, we have a doc going in depth. For now, we’ll try to stick to providing a high-level overview of what’s going on, so that we can grok the basic approach.)

Pulumi executes your application as a normal Node.js application. As such, when it hits the const videoBucket = new aws.s3.Bucket("videos") lines, it actually goes and creates those resources. When it then hits the videoBucket.onObjectCreated("onNewVideo", async (event) => { line this executes a normal line of JavaScript. Namely, onObjectCreated is a normal JavaScript function that will be passed the name parameter as the first arg, and the JavaScript function as the second arg. onObjectCreated eventually bottoms out with a call to a call to pulumi.runtime.serializeFunction. This function is the root of where our deep analysis of your JavaScript function analysis and translation will happen.

It’s worth pausing here. We can use all the standard approaches to function composition to build bigger functions out of smaller functions, even before we hit that serialization routine. The closures are built up in the V8 runtime as usual, and are eagerly awaiting the transformation into magic functions as soon as they are needed. Pretty cool!

Once we get to that point, using the awesome analysis APIs provided by TypeScript, we start introspecting the function instance, seeing what code it contains, and what external objects it references. The legal objects that can be included in the captured function’s environment include (but aren’t limited) to things like simple JavaScript objects, other functions (like computeDimensions), modules (like sharp), other Pulumi resources (like videoTopic), and even complex beasts like Promises. Basically, anything that Pulumi knows how to serialize and rehydrate inside the Lambda.

When Pulumi determines that these objects are referenced, it automatically includes enough information about them into the final translated Lambda code file so that they are available and can be effectively used at runtime. Thanks to JavaScript’s deep, dynamic introspection capabilities, as well as its rich APIs for creating nearly anything at runtime, it’s very possible to effectively hydrate out all the information present when Pulumi runs, and put it into a form that can be cheaply and accurately rehydrated into runtime objects again when the Lambda runs.

This analysis also understands the NPM package structure of an application and its dependencies, ensuring that necessary imported packages are properly included with the final Lambda. This analysis is also very smart about not including things that aren’t necessary at all. For example, it might drop information from the serialized form if it can prove that would never be observable, in addition to relying on built-in runtime functions being there without needing any sort of serialization. There are definite subtleties and interesting cases that can arise here, and for those very curious, reading the documentation linked above may be very enlightening.

Pulumi also understands diffs and dependencies, so updating is a cinch. Any changes to the code in the JavaScript function (including anything it depends on) is properly tracked and understood by Pulumi, allowing an easy development model where FaaS code can be easily modified and republished without jumping through extra hoops.

The Result? Simple serverless Functions

With this approach, serverless programming becomes dramatically simpler, whether it’s an AWS Lambda, Azure Function, or GCP Cloud Function. (Stay tuned, we’re hoping to bring this to Kubernetes FaaS offerings soon.)

In short, you just write event-driven JavaScript code that’s familiar and easy, you run pulumi up, and everything is taken care of from there. No YAML configuration files, no point and clicking in a cloud console UI, no fuss.

On top of all of that, because this is just code itself, and because these are normal APIs, other tooling (like your editor) knows exactly what is going on and can guide you through this. For example:

While there’s a lot of really cool tech going on under the covers here, we really hope that this ends up just feeling super-awesome to use for you. Now that we have this functionality, we wouldn’t want to ever write an AWS Lambda any other way!

Get started building serverless functions on Pulumi today!

Advanced TypeScript type FTW!

Cyrus Najmabadi — Wed, 19 Sep 2018 00:00:00 +0000

We at Pulumi love TypeScript for cloud apps and infrastructure, because of its rich type system and great ahead-of-time typechecking – making for a more productive inner loop and helping to find errors sooner. The typesystem magic behind how this works for infrastructure as code can be fascinating!

A core part of the Pulumi programming model is that we allow people to express complex dependency data that may eventually be available. Traditional JavaScript programming might expose that as a Promise, but we’ve taken that one step further by introducing a type we call:

type Input<T> = T | Promise<T> | Output<T>;
// Like a Promise<T>, but also keeps track of dependency information so we can figure
// out what the upstream/downstream impact is whenever any values change in the system
interface Output<T> { /* ... */ }

This complex type can often show up as inputs to all Pulumi objects like so:

interface VpcInput {
ipAddresses: Input<Input<string>[]>;
}

Breaking that down, it’s basically saying “I’ll take an array of strings. But those actual string values can individually be strings, promises-of-strings, or strings-carrying-dependency-information.” It even goes one step beyond that, because the entire array itself could be just an array-of-those-things, or a promise-of-array-of-those-things, or an array-of-those-things-with-dependency-information. Whew…!

This approach is great for people producing the data. As a producer I can do:

new Vpc({ ipAddresses: ["an-address"] }); // or even
new Vpc({ ipAddresses: ["an-address", computeAddressAsynchronously() ]}); // or even
new Vpc({ ipAddresses: ["an-address", computeAddressAsynchronously(), someDependency.address ]}); // or even
new Vpc({ ipAddresses: computeAnArrayAnyOfTheAboveAsynchrousnously() }); // etc. etc.

It’s super flexible, and let’s people naturally produce the values in whatever way they want without having to work too hard to make it conform to some very narrow type.

However, while easy to produce, this can sometimes be difficult to consume. For example, if you wanted to take in that Input<Input<string>[]> and then check if there was a very specific value in it, you might have to go through and do a bunch of work. You’d have to first deal with potentially getting a Input<string>[] or a Promise<Input<string>[]> or even an Output<Input<string>[]>. Then, once you even got to the underlying array, you’d have to deal with each potential element in it being a string… or a Promise<string>… or a… well… you get the idea. It’s not fun 😃.

Up until now, we’d supplied some simple helpers to make this more manageable. Our helpers would effectively ‘unwrap’ one layer of this sort of structure allowing you take the external value and deal with an internal value of a known shape. So it effectively worked like this:

function unwrap<T>(input: Input<T>): T { /* ... */ }
// so, you could then write:
const ipAddresses: Input<string>[] = unwrap(vpc.ipAddresses);

This helped things somewhat. But it still meant that as you processed that array you had to then unwrap each and every element. As our data model has grown, and we’ve tackled more and more complex domains, we started seeing code start to form the programming Pyramid of Doom, where you just kept on going deeper and deeper, unwrapping all the way. We started seeing this happen so often that we wanted to see if we there was anything we could do to make life much nicer for people using our APIs and using these helpers.

Our core goal was to change our ‘unwrap’ function from just peeling away one layer of this onion, to peeling away all layers. So, for example, if you started with an Input<Input<string>[]> you would just get back a plain old string[] that you could use completely naturally in all the ways you’d expect. We were initially uncertain if we could make this work, but thanks to the power of JavaScript and the expressivity of TypeScript, we think we found a great solution here.

We knew that providing the implementation such a function itself was not going to the true hard part. After all, we already had the code to peel back one layer. So peeling back all the layers was more a matter of just having the function call itself recursively when encountering things like arrays (or other objects that themselves contained Inputs).

The real hard part came in when were trying figure out how would we even express this in a type-safe manner TypeScript. After all, what’s the type signature when you effectively want to say:

function unwrap(input: Input<...MaybeHasInputsOrPromisesOrOutputsArbitrarilyDeep...>): ThatThingWithAllTheDeepInputsPromisesAndOutputsErased;

This was a big head scratcher for a while. But after exploring some of the powerful new features that TypeScript has been bringing about in recent releases, we finally found a great way to manage it. In the end, it ends up looking something like this:

type primitive = string | number | boolean | undefined | null;
type Unwrap<T> =
T extends Promise<infer U> ? UnwrapSimple<U> :
T extends Output<infer U> ? UnwrapSimple<U> :
UnwrapSimple<T>;
type UnwrapSimple<T> =
T extends primitive ? T :
T extends Array<infer U> ? UnwrappedArray<U> :
T extends object ? UnwrappedObject<T> :
never;
interface UnwrappedArray<T> extends Array<Unwrap<T>> {}
type UnwrappedObject<T> = {
[P in keyof T]: Unwrap<T[P]>;
};
function unwrap<T>(val: T): Unwrap<T>;

It’s a bit of a doozy containing a bunch of type definitions and the final function declaration that uses them. It makes use of many advanced TypeScript typing features. Including ‘Union Types’ (the ‘primitive’ type), ‘Mapped Types’ (which ‘UnwrappedObject’ is an example of), ‘Conditional Types’ (the types with ? and : in them) and ‘Inferred Types’ (the use of infer U in several places). You can read more about these in the Advanced Types documentation.

Put together, the Unwrap<T> itself is effectively a recursively defined structural pattern matching type. You can see it reference itself once you walk into UnwrappedArray<T> and UnwrappedObject<T> types. As it recurses, it matches the type it has and then ‘peels away’ the wrappings that have been caused by Promise<T> and Output<T>. As it hits Arrays and Objects, it dives deeper, unwrapping along the way. This is all manageable in TypeScript because it does this sort of matching and unwrapping in a lazy fashion, allowing us to express what is effectively an infinitely large pattern-matching type, without it having any trouble understanding it or applying it!

It amazes us how well this works and how expressive TypeScript is here. As you can see here, TypeScript completely understands what’s going on and will give you all the great type-checking support and tooling that we know and love:

Since adding support for this, we’ve been able to start using this new function across our own codebase and we’ve seen things get dramatically simpler. The pyramid-of-doom goes away and code becomes much cleaner and easier to read and maintain. JavaScript helped us write this system easily, but thanks to TypeScript we can express these complex intents and have the safety and understanding to do this sort of thing with confidence.

A special thanks to @DanielRosenwasser over from the TypeScript team for putting up with my constant pestering on how to work through this and deal with some especially thorny areas!

Simple, Reproducible Kubernetes Deployments

Alex Clemmer — Fri, 24 Aug 2018 00:00:00 +0000

Kubernetes is a powerful container orchestrator for cloud native applications that can run on any cloud – AWS, Azure, GCP – in addition to hybrid and on-premises environments. Its CLI, kubectl, offers basic built-in support for performing deployments, but intentionally stops short here. In particular, it doesn’t offer diffs and previews, the ability to know when a deployment has succeeded or failed, and why, and/or sophisticated deployment orchestration.

In this post, we’ll see how Pulumi, an open source cloud native development platform, can not only let you express Kubernetes programs in familiar programming languages, like TypeScript, instead of endless YAML templates, but also how Pulumi delivers simple and reproducible, yet powerful, Kubernetes deployment workflows.

Less YAML, More Robustness

Pulumi 0.15 introduced Kubernetes support to Pulumi. When we started working on this, we already loved being able to write in our favorite languages – with the benefits of IDEs, classes and functions, and reuse through packages – instead of YAML. But we felt just having great programming language alone wasn’t enough.

As we looked to how teams wanted to operationalize our Kubernetes support, we set our sights on one major area: delivering simple, reproducible application deployment workflows. When an app attempts to roll out, it should be obvious if it succeeded. If the rollout failed, on the other hand, errors should be clear and useful enough that most problems are simple to fix – and resuming where you left off after fixing should be similarly just as easy. Finally, all of this should be repeatable so that CI/CD is robust in production team environments.

Like many others, we’ve used kubectl apply to dump a pile of YAML into the API server. The command returns instantly, but what happens next? Is the app up? How does this tie back into CI/CD, so others on the team know what’s up with a deployment? Did something fail, or get stuck?

The vision in our heads, which we set out to build, was something more like this:

In this example, we can clearly see the entire set of resource objects being created, their ongoing status, and when and why something might have failed (in this case, a missing Docker image). This is a real screengrab of our CLI.

The service works in tandem with the CLI, so we always have a history and record of successful or failed deployments:

Let’s Deploy Some Code!

In this post, we’ll get a taste of this and several other aspects of the Pulumi workflow by deploying a very simple app – an nginx web server – to a Kubernetes cluster.

We’ll show how to use the Pulumi update command to get real-time information about a deployment’s progress. We’ll see how to use Pulumi’s notion of “stack outputs” to present information about successful deployments to the user – e.g. the public IP address allocated to an application after the load balancer spins up. Finally, we’ll see how to use Pulumi’s diff command to reason about the blast radius of an update to the application, before even attempting it.

If you’d like to follow along, you can find the code here. In the README, you’ll find instructions for the prerequisites – installing Pulumi, setting up a local or remote Kubernetes cluster, etc.

Application Config-as-Code

Our first task in our journey is to write a Kubernetes application that deploys nginx to the cluster and exposes it publicly to the Internet. Kubernetes ships out of the box with useful APIs for deploying applications, managing incremental rollouts of changes, and specifying how traffic is directed, all of which we will use in this example.

The code below as a slightly modified version of the “Hello World” Deployment example from the Kubernetes docs. We have chosen to write this Pulumi program in TypeScript, an excellent choice for a mix of dynamic productivity, static typing (meaning we will find errors sooner, often at compile time!), and provides instant access to the NPM ecosystem.

Note: It is also possible to directly deploy existing Kubernetes YAML objects, as a stepping stone. See the example here. This lets you reap all of the benefits of the deployment workflow called out in this post without needing to rewrite all of your Kubernetes YAML. It’s easy to then rewrite it piecemeal, one step at a time, after getting up and running.

This application has two major pieces:

The Deployment, which takes a template for an application, and then instantiates some user-specified number of copies (or replicas) of that template in the cluster.
The Service, which we will use to allocate a publicly-reachable IP address, and to direct traffic.

The code below from index.ts defines our application using these two APIs:

// nginx container, replicated 3 time.
const appName = "nginx";
const appLabels = { app: appName };
const nginx = new k8s.apps.v1beta1.Deployment(appName, {
 spec: {
 selector: { matchLabels: appLabels },
 replicas: 3,
 // The application template to replicate -- just the nginx container.
 template: {
 metadata: { labels: appLabels },
 spec: { containers: [{ name: appName, image: "nginx:1.15-alpine" }] }
 }
 }
});

// Allocate an IP to the nginx Deployment.
const frontend = new k8s.core.v1.Service(appName, {
 metadata: { labels: nginx.spec.apply(spec => spec.template.metadata.labels) },
 spec: {
 // Type `LoadBalancer` causes us to allocate a public IP address.
 type: "LoadBalancer",
 ports: [{ port: 80, targetPort: 80, protocol: "TCP" }],
 selector: appLabels
 }
});

This code creates 3 replicas of the nginx container, puts them behind a load balancer listening on port 80, and exposes it publicly to the Internet.

Right away, we notice:

Pulumi does not define a new API for Kubernetes; it simply uses the same schema as the upstream Deployment and Service APIs. In fact, it is generated from the Kubernetes OpenAPI specification, so it is always up-to-date and complete.
By using TypeScript, we have the ability to eliminate repetition and boilerplate with familiar programming language constructs, like we did with our appLabels variable that is reused multiple times. Another example is the use of a function to capture common patterns, as can be seen in our port of the ever-familiar guestbook application.

Deploying the Application

If we were deploying normal Kubernetes YAML, we’d run kubectl apply. This would return instantly, and it would be up to us to use ancillary commands (e.g. kubectl get service) to figure out if the application succeeded.

The Pulumi equivalent is to run pulumi up. This evaluates our program, figures out the diff and incremental update plan, shows us a preview of what it will do, and ultimately carries it out. Under the hood, this is using the Kubernetes Go client library, and – although we will still use kubectl to inspect and interact with cluster state, the entire deployment process is subsumed by pulumi.

Indeed, if we take our project and simply run pulumi up we’ll see something like the following:

Compared to kubectl apply, many things are happening:

We see that pulumi up blocks until all Kubernetes resources have completed initialization. In this case, that includes a Deployment and a Service.
We see intermediate status messages as Kubernetes resources make progress towards initialization. For example the Service called nginx alerts us when (1) it successfully found application containers to direct traffic to, and (2) that an IP address has been allocated to it. If things fail, we will see that too.
All deployment is coordinated with a state manager so that concurrent updates are handled correctly in a team setting, rather than potentially clobbering one another.
If you look closely, at the end of the gif loop, you’ll notice some green text that looks like this:
```
 ---outputs:---
frontendIp: "35.226.79.25"
```
This is the IP that was allocated to the Service, which in turn directs traffic to our nginx containers. If you run pulumi up yourself and open that IP address in your browser, easily available with the pulumi stack output frontendIp command, you will actually see the nginx landing page.

Using Stack Outputs

As a brief aside, you might have wondered: how did this IP address get here?

When kubectl apply completes, it is difficult to automatically obtain values like the IP address allocated to a Service. It can take many minutes for the IP address to be allocated, and most users simply resort to running kubectl get service repeatedly, until it appears. This is cumbersome and makes it hard to use reliably.

In Pulumi, such values are first-class citizens – called stack outputs. Because Pulumi has a notion of “done-ness”, and because pulumi up will block until all resources are finished initializing, it is trivial to “export” values from a fully-initialized resource. In this case, frontendIp simply contains the IP address obtained from the fully-initialized Service that directs traffic to the nginx containers – the IP address allocated to it.

We could take any value from any Kubernetes resource and put it in any variable – in this case, we just happen to have exported the IP address using a variable frontendIp. The code to do this export looks like this (at the bottom of index.ts):

export const frontendIp = frontend.status.apply(
 status => status.loadBalancer.ingress[0].ip);

Obtaining this value from the CLI is trivial using the pulumi stack output command. Here we use curl to get find the title of the nginx landing page that frontendIp points at.

$ curl -sL $(pulumi stack output frontendIp) | grep "<title>"
<title>Welcome to nginx!</title>

Updating our Application

Pulumi makes it easy to incrementally update our application too, after the initial creation. pulumi up just handles this automatically for us, by comparing its notion of a goal state to the cluster’s current state, and using that to devise a plan. Because of this, we get reliable preview diffs.

When running kubectl apply, it is often difficult to reason about what changes will be made to a running application, before actually carrying out the changes. This makes it difficult to predict the impact an update will have, including whether there would be potential downtime. Put simply, this can lead to accidents.

In contrast, in Pulumi the idea of a diff is a first-class concept, and is front and center in the workflow. To see this in action, try changing the container image from nginx:1.15-alpine to nginx:alpine-1.16-alpine in index.ts, and then run pulumi preview --diff. You will see something like this:

You can see several things happening here:

The diff captures the change in the nginx image.
It reports that the nginx Deployment resource will be updated in-place. Replaces may also be replaced or deleted, which would be evident from the diff also.

The intention here is to give users an intuition for the blast radius of the changes to a Kubernetes application.

Running diffs manually by hand isn’t necessary, despite being useful. Unless you explicitly bypass it, running pulumi up will always show you a preview first and confirm that you’d like to proceed before actually making any changes. And because Pulumi is always tracking old states, rollback afterwards is easy also.

This CLI workflow is great for the dev inner loop, however the Pulumi GitHub App also integrates these previews and diffs with your CI/CD system, by enlightening your GitHub Pull Requests with potential update impacts, while your team still has a chance to discuss changes inside the usual PR workflow, enabling powerful GitOps scenarios.

Conclusion

In this article, you’ve seen that you can express Kubernetes apps in real code, instead of YAML, and you’ve gotten a taste of the pulumi up deployment workflow, especially compared to kubectl.

Try it out now by heading over to our Getting Started page.

We are just getting started. In the coming weeks we will be sharing more around other deployment scenarios, including A/B traffic splitting, canaries guarded by Prometheus metrics, Kubernetes application code living alongside AWS infrastructure, triggering of cascading rollouts based on ConfigMap changes… And much, much, more.

If you have specific use cases you’d like to see us tackle, don’t hesitate to reach out, either on GitHub or in our Pulumi Community Slack. We’d love to hear from you!

Program the Cloud with 12 Pulumi Pearls

Joe Duffy — Wed, 25 Jul 2018 00:00:00 +0000

In this post, we’ll look at 12 “pearls” – bite-sized code snippets – that demonstrate some fun ways you can program the cloud using Pulumi. In my introductory post, I mentioned a few of my “favorite things”. Now let’s dive into a few specifics, from multi-cloud to cloud-specific, spanning containers, serverless, and infrastructure, and generally highlighting why using familiar languages is so empowering for cloud scenarios. Since Pulumi lets you do infrastructure-as-code from the lowest-level to the highest, we will cover a lot of interesting ground in short order.

If you want to follow along and try some of this out, Pulumi is open source on GitHub, free to download and use, and the quickstart will acquaint you with the CLI. Most of the examples are directly runnable and available in our examples repo, and are just a pulumi up away, unlike other approaches that require you to point-and-click around in your cloud’s console, and/or author reams of yucky YAML. And you get to use familiar languages!

Here is an index of the pearls in case you want to dive straight into one in particular:

Infrastructure:

Declare cloud infra using a familiar language (with loops!)
Make a reusable component out of your cloud infra

Serverless:

Go serverless without the YAML
Capture state in your serverless funcs, like real lambdas
Simple serverless cron jobs
Run Express-like serverless SPAs and REST APIs at near zero cost

Containers:

Deploy production containers without the fuss
Use containers without Dockerfiles
Invoke a long-running container as a task

General Tips and Tricks:

Use code to avoid hard-coding config
Use config to enable multi-instantiation and code reuse
Give your components runtime APIs

Even if you’re uninterested in low-level infrastructure, it can be fun to work through these examples; it’s “turtles all the way down” with Pulumi and doing so can help understand how the system works. And similarly, it can be fun to see the high-level scenarios these building blocks facilitate, even if you just want to stand up containers and functions.

And with that, let’s dive in.

Infrastructure

Familiar Languages

[ Runnable Example ]

Pulumi gives you a way to express infrastructure configuration using your favorite programming language. In this article, we’ll use TypeScript on Node.js, as it delivers great productivity by blending dynamic and static typing with the NPM ecosystem of reusable packages.

At the lowest layer, there are packages for all major cloud providers – AWS, Azure, Google Cloud – in addition to Kubernetes and OpenStack. So, if you want an EC2 instance, Azure CosmosDB, or Kubernetes Pod, you just new up an object. From there, Pulumi uses an infrastructure-as-code approach similar to using AWS CloudFormation, Azure Resource Manager, Google Resource Manager, Kubernetes or Helm YAML, or Terraform – just without the YAML DSLs.

The strength of using a language truly begins to shine when you go beyond new, however. Using a language gives you control structures, like for loops and if branches. This is easy to take for granted, but compared to existing YAML DSLs, it is very powerful.

For example, let’s create three EC2 VMs and export their IP addresses. Normally you’d need to copy-and-paste, however for loops to the rescue!

index.ts:

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

let webSg = new aws.ec2.SecurityGroup("web-secgrp", {
 ingress: [
 { protocol: "tcp", fromPort: 80, toPort: 80, cidrBlocks: ["0.0.0.0/0"] },
 ],
});

let webServers = [];
for (let i = 0; i < 3; i++) {
 webServers.push(new aws.ec2.Instance(`web-server-${i}`, {
 instanceType: "t2.micro",
 ami: "ami-6869aa05", // us-east-1-only
 securityGroups: [ webSg.name ],
 userData: `#!/bin/bashn` +
 `echo 'Hello, World #${i}!' > index.htmln` +
 `nohup python -m SimpleHTTPServer 80 &n`,
 }));
}
export const publicHostnames = webServers.map(s => s.publicDns);

This provisions three web servers, each of which runs a simple Python webserver.

Of course, this can unlock far more sophisticated scenarios. For example, our own AWS Infrastructure package offers core AWS infrastructure components using AWS’s own best practices, and a community member built an AWS Virtual Private Cloud (VPC) component that automatically distributes subnets across all availability zones in a region, including smartly calculating the CIDR addresses, hiding lots of the messy details of AWS networking.

Reusable Components

[ Runnable Example ]

Speaking of components, this is another benefit of using familiar languages: abstraction. This includes the ability to hide uninteresting details through encapsulation, and create bigger things out of smaller things, a key to how we’ve become so productive with programming languages generally over the years. Applied to infrastructure, this enables some powerful scenarios.

For instance, perhaps you want a standard base class for all servers in your organization, enforcing security policy or even just naming conventions. Or maybe you want to ensure there is an Envoy proxy sidecar for all of your Kubernetes pods. No matter the scenario, we call these things “components” and Pulumi has a rich model that supports parents and children.

To stick with the running example, let’s make a WebServer class that internally creates the EC2 VM so that callers don’t need to know messy details like how to create and configure a SecurityGroup and choosing the right image:

web.ts:

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

let webSg = new aws.ec2.SecurityGroup("web-secgrp", {
 ingress: [
 { protocol: "tcp", fromPort: 80, toPort: 80, cidrBlocks: ["0.0.0.0/0"] },
 ],
});

export class WebServer {
 public readonly vm: aws.ec2.Instance;

 constructor(name: string) {
 this.vm = new aws.ec2.Instance(`${name}`, {
 instanceType: "t2.micro",
 ami: "ami-6869aa05", // us-east-1-only
 securityGroups: [ webSg.name ],
 userData: `#!/bin/bashn` +
 `echo 'Hello from ${name}!' > index.htmln` +
 `nohup python -m SimpleHTTPServer 80 &n`,
 });
 }
}

Now we can go back to our original program and tidy it up a bit:

index.ts:

import { WebServer } from "./web";

let webServers = [];
for (let i = 0; i < 3; i++) {
 webServers.push(new WebServer(`web-server-${i}`));
}
export const publicHostnames = webServers.map(s => s.vm.publicDns);

Not only is the result simpler, but we now have a way to divvy up responsibilities within a team, helping Dev and DevOps to work better together.

This example used purely local components, but you can of course publish and consume any old packages from your favorite package manager – including private registries for your own team.

We will return to these examples later on and improve them to be more reusable through configuration, however let’s first tour some fun serverless and container pearls.

Serverless

No YAML

[ Runnable Example ]

Let’s shift gears and jump into serverless. Pulumi is unique in that its goal is to be a platform for all aspects of modern cloud programming, so that includes serverless, in addition to the abovementioned infrastructure examples and the soon-to-be-mentioned container ones. Most real-world examples we see in fact mix all of these things together in the same program.

Because of the way it uses familiar languages, there are great benefits to serverless programming in Pulumi. No YAML required – just write lambdas in your favorite language, and our compiler/runtime magic will deal with them. But first, let’s start simple.

The AWS Serverless package provides event sources for all of the possible AWS Lambda triggers. This leverages the aws.serverless.Function abstraction that takes a lambda in your language and translates it into a package suitable for uploading to AWS. No need to embed code in YAML files, manually upload to S3, etc. Pulumi handles all of this including versioning.

Let’s look at a simple example that simply posts a Slack message for every new message that arrives in an SQS queue (a new capability recently added to AWS). The way you express serverless functions in Pulumi is by writing ordinary lambdas and the way you hook them up to event sources is by using an event-driven style on your existing cloud resources:

index.ts:

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

let queue = new aws.sqs.Queue("mySlackQueue");
serverless.queue.subscribe("mySlackPoster", queue, async (e) => {

let slack = require("@slack/client");
let client = new slack.WebClient(config.slackToken);
 for (let rec of e.Records) {
 await client.chat.postMessage({
 channel: config.slackChannel,
 text: `*SQS message ${rec.messageId}*:n${rec.body}n`+
 `(with :love_letter: from Pulumi)`,
 as_user: true,
 });
 console.log(`Posted SQS message ${rec.messageId} to ${config.slackChannel}`);
 }
});
export const queueURL = queue.id;

The code and instructions for running this example are available in our examples repo.

Serverless programs written in this style feel just like your favorite event-driven frameworks, and – because these are just ordinary lambdas in your language of choice – they compose in all the usual ways, unlocking some fascinating future possibilities (like serverless Spark and/or RxJS). Behind the scenes, Pulumi is doing the hard work to extract out the body of the function, rewrite it minimally but as needed to wire it up to AWS Lambda, and package it up. Subsequent deployments are as easy as the first one, as Pulumi does diffing to compute the minimal deltas.

Not everybody will want to mix infrastructure definitions and runtime code like this. Because these are just ordinary programs, you are free to split code into submodules and structure your workspace as you see fit. In fact, you can create distinct stacks for the different pieces.

This example is AWS-specific, however the Pulumi Cloud Framework offers several multi-cloud serverless (and container) capabilities. We will see some examples of that package in action below, however being able to target your cloud of choice directly means you can use all of its underlying features.

Real Lambdas

[ Runnable Example ]

Pulumi also lets you capture state in your serverless functions. This is one of the major advantages to this approach; normally you’d need to awkwardly arrange for such state to be passed into your function through some sideband mechanism, such as environment variables.

In Pulumi, we just capture state. Just like in your favorite language.

Let’s say we want the Slack information above to be configurable – a good idea, since the Slack token is a secret that should be configured using the –secret flag. To do so, first let’s create a config module:

config.ts:

import * as pulumi from "@pulumi/pulumi";
let config = new pulumi.Config(pulumi.getProject());

export const slackChannel = config.get("slackChannel") || "#general",
export const slackToken: config.require("slackToken");

And now let’s go back to our above program, and use the config module for these properties. Notice that we simply capture a reference to the config module – that’s it!

index.ts:

import * as config from "./config";
import * as aws from "@pulumi/aws";
import * as serverless from "@pulumi/aws-serverless";

let queue = new aws.sqs.Queue("mySlackQueue");
serverless.queue.subscribe("mySlackPoster", queue, async (e) => {
 let slack = require("@slack/client");
 let client = new slack.WebClient(config.slackToken);

 for (let rec of e.Records) {
 await client.chat.postMessage({
 channel: config.slackChannel,
 text: `*SQS message ${rec.messageId}*:n${rec.body}n`+
 `(with :love_letter: from Pulumi)`,
 as_user: true,
 });
 console.log(`Posted SQS message ${rec.messageId} to ${config.slackChannel}`);
 }
});
export const queueURL = queue.id;

We often call this “capture by serialization” because, of course, the captured state is marshaled into the serverless function’s package, and then unmarshaled at runtime at the time of use. The semantics of capture are specific to each language, but for JavaScript, we do a deep serialization of the object, including its prototype chain, so that the full structure is preserved.

Because of this, functions are even available. We use this capability to let you capture resources by-value that internally have references to a live cloud resource. We will see that next in our serverless cron job example.

Cron Jobs

[ Runnable Example ]

Pulumi’s Cloud Framework has an ultra-straightforward timer module that lets you schedule cron jobs that run serverless functions. This is the easiest way to get up and running with serverless functions, because you don’t even need any other resources to trigger events from.

There are several ways to schedule a timer, depending on your stylistic preferences. These examples simply print the current time to the console on a given interval:

index.ts:

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

// Run a timer every minute:
cloud.timer.interval("interval-timer", { minutes: 0 }, () => {
 console.log(`interval-timer: ${Date.now()}`);
});

// Run a timer every minute (cron-style expression):
cloud.timer.cron("cron-timer", "0 * * * * *", () => {
 console.log(`cron-timer: ${Date.now()}`);
});

// Run a timer every day at 7:30 UTC:
cloud.timer.daily("daily-timer", { hourUTC: 7, minuteUTC: 30 }, () => {
 console.log(`daily-timer: ${Date.now()}`);
});

// Run a timer at the 45th minute UTC of every hour:
cloud.timer.hourly("hourly-timer", { minuteUTC: 45 }, () => {
 console.log(`hourly-timer: ${Date.now()}`);
});

To make things slightly more interesting, let’s write a serverless timer that fetches the Hacker News homepage every hour and stashes it into a document database:

index.ts:

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

let snapshots = new cloud.Table("snapshots");
cloud.timer.daily("daily-yc-snapshot", { hourUTC: 0, minuteUTC: 0 }, () => {
 let req = require("https").get("https://news.ycombinator.com", (res) => {
 let content = "";

 res.setEncoding("utf8");
 res.on("data", (chunk) => { content += chunk });
 res.on("end", () => {
 snapshots.insert({ date: Date.now(), content: content });
 });
 });
 req.end();
});

We are using the ability to capture a reference to our cloud.Table and call functions on it, like insert. Of course, the body of that function can do absolutely anything that you’d like.

REST APIs

[ Runnable Example ]

Us Node.js programmers love web frameworks, whether that be serving static content using a single page application (SPA) built using React.js, Vue.js, or Angular.js, a program built using dynamic server-side logic using Express.js, or some combination thereof. Serverless offers a way to run these programs at incredible density and low cost, often reducing a VM- or container-based solution to 1/10th its cost (or better). The problem is, this usually means abandoning productive frameworks, and resorting to YAML, hand-authoring Swagger files, and configuring complex API Gateway machinery – all foreign concepts when you just want to run a website.

Pulumi lets you just write code to host both static and dynamic content simply, using its cross-cloud framework’s cloud.API abstraction. It has been designed to have a familiar Node.js feel. The following example serves all static content underneath my www directory at the root, and provides a simple GET endpoint at /hello that returns a { hello: "World!" } JSON object:

index.ts:

import * as cloud from "@pulumi/cloud";
// Create a new API endpoint:
let app = new cloud.API("my-app");
// Serve static files from the `www` folder (using AWS S3):
app.static("/", "www");
// Serve a simple REST API on `GET /hello` (using AWS Lambda):
app.get("/hello", (req, res) => res.json({ hello: "World!" }));
// Export the public URL for the HTTP service:
export const url = app.publish().url;

All of the usual verbs are available – post, patch, etc. – as is support for middleware.

The structure of my local filesystem will demonstrate how some of this ties together:

.
├── Pulumi.yaml
├── index.ts
├── package.json
└── www
├── favicon.png
└── index.html
1 directory, 5 files

Again, all we need to do is pulumi up, and Pulumi will figure out what has changed. So, if we are building an SPA using React.js, etc., then we would simply have a build step that updates the content, and the next time we run pulumi up, it will figure out what has changed and make the minimal set of updates. Similarly, if we edit a dynamic function, it will update just the function.

As you can imagine, things get fun when you start mixing scenarios. Say we wanted a web frontend to our Hacker News timer fetcher above. Thanks to the way we can simply capture a reference to the snapshots database and use it in the body of our API, this is extremely trivial.

Per the earlier conversation around mixing infrastructure and application code, some folks prefer to split the routes from the application code. This is a fine convention, and easy to do:

index.ts:

import * as cloud from "@pulumi/cloud";
import * as routes from "./app/routes";

// Create an API like before, but use a routes module instead of defining inline:
let app = new cloud.API("my-app");
app.get("/hello", routes.hello);

export const url = app.publish().url;

For now, Pulumi only offers an AWS implementation of these APIs, but more clouds are on their way!

Containers

Easy Deployment

[ Runnable Example ]

Let’s shift gears again and take a look at containers. Pulumi supports programming against raw container orchestrators – Amazon’s ECS, Azure’s ACS, Google Cloud’s GKE, Kubernetes directly, and so on – using the cloud resources directly. In this mode, Pulumi is entirely unopinionated about how containers are built, published, and deployed to your orchestrator.

It is important that Pulumi supports that low-level approach, and is what distinguishes it compared to PaaS-like offerings. This entails significant spelunking at a level that is only loosely connected to the task of standing up a container, however, which can be time-consuming and frustrating for many developers. To make this common case easier, Pulumi also offers higher-level abstractions to make these common cases easier, similar in spirit to Docker Compose, except that you can mix these abstractions with all your other cloud resources.

For example, to create a load balanced Nginx container using an image from the Docker Hub:

index.ts:

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

let nginx = new cloud.Service("nginx", {
 image: "nginx",
 ports: [{ port: 80 }],
 replicas: 2,
});

export const url = nginx.defaultEndpoint;

This is all you need to run Nginx with 2 load balanced replicas listening on port 80. By default, this will run in Fargate when targeting AWS, which means you can skip the complications of configuring an orchestrator. After running pulumi up, the auto-assigned URL will be printed.

The image directive supports any normal Docker image URL, so private registries work just as well as the default public Docker Hub. And there are a number of other supported properties for memory and CPU constraints, advanced port mapping, and volumes.

Now things get a bit more interesting. Let’s say we wanted to build our own custom container instead. Normally that would mean defining a Dockerfile, provisioning a private registry, and manually building and publishing your image to the registry, and then consuming that container image from the registry. That’s a lot of boilerplate scripting!

Pulumi unifies all container building, publishing, and consumption underneath a simple pulumi up:

index.ts:

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

let nginx = new cloud.Service("nginx", {
 build: ".",
 ports: [{ port: 80 }],
 replicas: 2,
});

export const url = nginx.defaultEndpoint;

Dockerfile:

FROM nginx
COPY ./www /usr/share/nginx/html

This is trivial Dockerfile that derives from the nginx base image and copies the ./www directory into the Nginx HTML target so that it will be served up. This is our directory structure:

.
├── Dockerfile
├── Pulumi.yaml
├── index.ts
├── package.json
└── www
├── favicon.png
└── index.html
1 directory, 5 files

Of course, this Dockerfile could be arbitrarily complex, using any Docker image.

No Dockerfiles

[ Runnable Example ]

The above example showed you how to create services that use Docker containers, either via a pre-built image stored in a registry like the Docker Hub, or by building one from a Dockerfile. The cloud.Service class supports a third possibility, which is really fun, as it takes advantage of Pulumi’s serverless programming model earlier to define a container and its service.

Imagine we want to define a simple Node.js webserver rather than using Nginx like this. Perhaps it uses Express.js. For this blog post, however, let’s stick with the most basic http-module-based webserver:

index.ts:

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

let www = new cloud.Service("www", {
 function: () => {
 let rand = Math.random();
 require("http").createServer((req, res) => {
 res.end(`Hello, world! (from ${rand})`);
 }).listen(80);
 },
 ports: [{ port: 80 }]
 memory: 128,
 replicas: 2,
});

export const url = www.defaultEndpoint;

This code defines a load balanced service, backed by a container that Pulumi builds on your behalf out of the body of the function provided in the program, all done with a simple pulumi up gesture. This function, of course, can close over other state just like the earlier serverless examples, including cloud resources, making it as easy as can be to connect your microservices.

Long Running Containers as Tasks

[ Runnable Example ]

The above examples are great if what you want is a load balanced, long-running service. Sometimes a container is useful simply for executing a long-running task, or one that has very specific requirements about its execution environment (such as a specific base image).

For those cases, a cloud.Task is just what the doctor ordered. Task supports all the same construction techniques as Service, so you can give it a pre-built image, a build directive, or an inline function. For purposes of illustration, let’s build a custom Dockerfile that performs an FFMPEG transformation, to extract a thumbnail anytime someone adds a video to a bucket:

index.ts:

let cloud = require("@pulumi/cloud-aws");
// A bucket to store videos and thumbnails.
let videos = new cloud.Bucket("bucket");
// A task which runs an FFMPEG transform to extract a thumbnail image.
let ffmpegThumbnailTask = new cloud.Task("ffmpegThumbTask", {
 build: ".",
 memoryReservation: 512,
});

// When a new video is uploaded, run the FFMPEG task on the video file.
videos.onPut(
 "onNewVideo",
 args => {
 let file = args.key;
 ffmpegThumbnailTask.run(
 {
 environment: {
 "S3_BUCKET": videos.bucket.name.get(),
 "INPUT_VIDEO": file,
 "TIME_OFFSET": file.substring(file.indexOf('_')+1, file.indexOf('.')).replace('-',':'),
 "OUTPUT_FILE": file.substring(0, file.indexOf('_')) + '.jpg',
 },
 });
 },
 { keySuffix: ".mp4" });

exports.bucketName = videos.bucket.name;

Dockerfile:

FROM jrottenberg/ffmpeg
RUN apt-get update && apt-get install python-dev python-pip -y && apt-get clean
RUN pip install awscli
WORKDIR /tmp/workdir
ENTRYPOINT
echo "Starting ffmpeg task... " &&
echo "Copying video from s3://${S3_BUCKET}/${INPUT_VIDEO} to ${INPUT_VIDEO}..." &&
aws s3 cp s3://${S3_BUCKET}/${INPUT_VIDEO} ./${INPUT_VIDEO} &&
ffmpeg -v error -i ./${INPUT_VIDEO} -ss ${TIME_OFFSET} -vframes 1 -f image2 -an -y ${OUTPUT_FILE} &&
echo "Copying thumbnail to S3://${S3_BUCKET}/${OUTPUT_FILE} ..." &&
aws s3 cp ./${OUTPUT_FILE} s3://${S3_BUCKET}/${OUTPUT_FILE}

Notice that, just like before, this is backed by an ordinary Dockerfile. This example actually showcases serverless and containers living alongside one another in harmony. Notice how we kick off the task – simply by capturing a reference to the Task from the serverless event handler, and invoking its run method. This leverages Pulumi’s ability to give resources like Tasks custom APIs that can be invoked at runtime, something we will return to again later on.

General Tips and Tricks

Avoid Hard-Coding Config

Let’s return to our webserver example from earlier. Unfortunately, this code will only work in one region, because we hard-coded the "ami-6869aa05" image name (AMI). (Image names in AWS are region-specific.) In general, we prefer to build Pulumi programs that can be multi-instantiated across different regions. Pulumi’s stacks model streamlines this workflow, making it easy to spin up fresh copies of your entire application and/or infrastructure when you need to scale, while also reducing friction during development and testing. Such hard-coding is a definite code smell and impediment, however.

Because we are using a familiar language, we can do anything that general-purpose languages can do. That includes dynamically querying sources of information which, in this case, can be used to avoid hard-coding. We can even use the AWS SDK, which gives us full access to all AWS functionality:

ami.ts:

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

export function getLinuxAmi(): Promise<string> {
 return new Promise<string>((resolve, reject) => {
 let ec2 = new (require("aws-sdk")).EC2({ region: aws.config.requireRegion() });
 ec2.describeImages(
 {
 Owners: [ "amazon" ],
 Filters: [{
 Name: "name",
 Values: [ "amzn-ami-hvm-????.??.?.x86_64-gp2" ],
 }],
 },
 (err: any, data: any) => {
 if (err) {
 reject(err);
 } else {
 let newestImage: string | undefined;
 let newestImageDate: number | undefined;
 for (let image of data.Images) {
 let imageDate = Date.parse(image.CreationDate);
 if (!newestImage || !newestImageDate ||
 imageDate > newestImageDate) {
 newestImage = image.ImageId;
 newestImageDate = imageDate;
 }
 }
 if (newestImage) {
 console.log(`AMI: ${newestImage} (${newestImageDate})`);
 resolve(newestImage);
 } else {
 reject("No Linux AMI found for the current region");
 }
 }
 },
 );
 });
}

I’ll be the first to admit that this is code that only a mother could love. Even better would be to wrap it up in a reusable NPM package that others can use without the boilerplate! Either way, it’s very powerful to have the full capabilities of a language at our fingertips, as this sort of thing simply isn’t possible in other infra-as-code solutions.

Now that we have this function, we can revisit the way we set the AMI property on our VMs:

web.ts:

import * as aws from "@pulumi/aws";
import { getLinuxAmi } from "./ami";

let webSg = new aws.ec2.SecurityGroup("web-secgrp", {
 ingress: [
 { protocol: "tcp", fromPort: 80, toPort: 80, cidrBlocks: ["0.0.0.0/0"] },
 ],
});

export class WebServer {
 public readonly vm: aws.ec2.Instance;

 constructor(name: string) {
 this.vm = new aws.ec2.Instance(`${name}`, {
 instanceType: "t2.micro",
 ami: getLinuxAmi(),
 securityGroups: [ webSg.name ],
 userData: `#!/bin/bashn` +
 `echo 'Hello from ${name}!' > index.htmln` +
 `nohup python -m SimpleHTTPServer 80 &n`,
 });
 }
}

Given this change, we can safely deploy our WebServer to any AWS region.

Multi-Instantiation and Code Reuse

In the webserver example, we used the aws.config.requireRegion() function to obtain the configured AWS region. Using configuration in this manner lets us multi-instantiate stacks; in other words, to easily stand up multiple copies of a service, application, or infrastructure.

We can even make the quantity configurable using Pulumi’s config system:

index.ts:

import { WebServer } from "./web";
import { Config, getProject } from "@pulumi/pulumi";

let config = new Config(getProject());
let webServers = [];
let webServersCount = config.getNumber("count") || 3;
for (let i = 0; i < webServersCount; i++) {
 webServers.push(new WebServer(`web-server-${i}`));
}

export const publicHostnames = webServers.map(s => s.vm.publicDns);

Given this specific program, we can easily change the number of servers created from the default of three, to something larger:

$ pulumi config set count 7

There are plenty of opportunities for configuration like this, like the machine size. By making such settings configurable, different environments can easily have different settings, while still sharing the same code beneath them, eliminating copy-and-paste and its associated pitfalls.

Give Components Runtime APIs

[ Runnable Example ]

As our final example, let’s see how to give your own components APIs that can be invoked at runtime. We’ve already seen this a few times now, such as managing data in a cloud.Table that has been captured in a lambda, and cloud.Task’s run method. Pulumi is built to be extensible, so you can define your own abstractions just like these with APIs too.

For this example, let’s take a simple Redis cache service and turn it into a component. After doing so, we can then add simple get/set APIs on it that let you interact with the cache at runtime in simple ways. By providing this sort of abstraction, we open up interesting possibilities. For instance, our default implementation can use a custom container-backed service, via cloud.Service, but opt to use a simpler hosted solution when running in a public cloud – AWS ElastiCache, Azure Redis Cache, or Memorystore in Google Cloud.

To make our component, we will simply allocate a cloud.Service in the constructor, taking an optional memory parameter to control its memory reservation. We are using configuration to read the Redis password using Pulumi’s built-in secrets mechanism. To give that component APIs, we just define methods on the class that access Redis through its own NPM package, and that’s it! The way lambda capture works will ensure that these functions are accessible:

cache.ts:

import * as cloud from "@pulumi/cloud";
import * as config from "./config";

// A simple cache abstraction that wraps Redis.
export class Cache {
 public readonly get: (key: string) => Promise<string>;
 public readonly set: (key: string, value: string) => Promise<void>;
 private readonly redis: cloud.Service;

 constructor(name: string, memory: number = 128) {
 this.redis = new cloud.Service(name, {
 image: "redis:alpine",
 memory: memory,
 ports: [{ port: 6379 }],
 command: ["redis-server", "--requirepass", config.redisPassword],
 });
 }

 public async get(key: string): Promise<string> {
 let client = await this.createRedisClient();
 return new Promise<string>((resolve, reject) => {
 client.get(key, (err: any, v: any) => {
 if (err) reject(err);
 else resolve(v);
 });
 });
 }

 public async set(key: string, value: string): Promise<void> {
 let client = await this.createRedisClient();
 return new Promise<void>((resolve, reject) => {
 client.set(key, value, (err: any, v: any) => {
 if (err) reject(err);
 else resolve();
 });
 });
 }

 private async createRedisClient(): Promise<any> {
 let ep = (await this.redis.defaultEndpoint).get();
 return require("redis").createClient(
 ep.port, ep.hostname, { password: config.redisPassword });
 }
 }
}

Because this is just a class, we have all the standard programming facilities available to us. If we wanted to specialize it to use our cloud’s hosted Redis services, we could do that using the standard techniques, including conditional code or, slightly more elegantly, using concrete subclasses for the different options.

Now that we’ve defined our cache, we can create an instance, and then use it from within a callback, such as a serverless API implementation. This is a fairly complex application that acts as a URL shortener, with both GET and POST endpoints, but really shows off the power of combining many of the techniques we’ve seen throughout this post:

index.ts:

import * as cloud from "@pulumi/cloud";
import * as cache from "./cache";

// Create a URL shortener app and a table to hold shortened URLs.
let app = new cloud.API("shortener");
let urlTable = new cloud.Table("urls", "name");

// Use our cache component to cache frequently accessed URLs.
let urlCache = new cache.Cache("urlcache");

// GET /url lists all URLs currently registered.
endpoint.get("/url", async (req, res) => {
 try {
 res.status(200).json(await urlTable.scan());
 } catch (err) {
 res.status(500).json(err.stack);
 }
});

// GET /url/{name} redirects to the target URL based on a short-name.
endpoint.get("/url/{name}", async (req, res) => {
 let name = req.params["name"];
 try {
 // First try the Redis cache. If we miss, consult the table.
 let url = await urlCache.get(name);
 if (url) {
 res.setHeader("X-Powered-By", "redis");
 } else {
 let value = await urlTable.get({ name });
 if (value && value.url) {
 url = value.url;
 urlCache.set(name, url); // cache for next time.
 }
 }

 // If we found an entry, 301 redirect to it; else, 404.
 if (url) {
 res.setHeader("Location", url);
 res.status(302);
 res.end("");
 } else {
 res.status(404);
 res.end("");
 }
 } catch (err) {
 res.status(500).json(err.stack);
 }
});

// POST /url registers a new URL with a given short-name.
endpoint.post("/url", async (req, res) => {
 let url = req.query["url"];
 let name = req.query["name"];

 try {
 // Insert into the table and our URL cache.
 await urlTable.insert({ name, url });
 await urlCache.set(name, url);
 res.json({ shortenedURLName: name });
 } catch (err) {
 res.status(500).json(err.stack);
 }
});

export const url = endpoint.publish().url;

Notice that we can capture and use our Cache component just like we can the cloud.Table!

We’ve only scratched the surface of what’s possible with components and custom APIs, however hopefully you’re starting to get a sense of why this is such a powerful capability.

Winding Down

In this post, we’ve seen how Pulumi can define infrastructure, containers, and serverless cloud software, often combining many of the techniques together to build powerful distributed applications. This includes programming to specific resources that your cloud of choice provides, in addition to writing higher level cloud programs that are able to target many clouds (expect more multi-cloud progress here in the weeks to come – including Kubernetes). Each pearl is a topic unto itself; we’d love your feedback on what topics to dig into next.

Happy hacking – and have fun programming the cloud!

Serving a Static Website on AWS with Pulumi

Chris Smith — Tue, 17 Jul 2018 00:00:00 +0000

Hello! This post covers using Pulumi to create the infrastructure for serving a static website on AWS. The full source code for this example is available on GitHub.

Setting up the infrastructure to serve a static website doesn’t sound like it would be all that difficult, but when you consider HTTPS certificates, content distribution networks, and attaching it to a custom domain, integrating all the components can be quite daunting.

Fortunately this is a task where Pulumi really shines. Pulumi’s code-centric approach not only makes configuring cloud resources easier to do and maintain, but it also eliminates the pain of integrating multiple products together.

This isn’t a hypothetical benefit of using the Pulumi programming model. We use a setup similar to the one described in this post for powering our own static websites, like www.pulumi.com and get.pulumi.com.

Overview

The architecture we will use for the website is to follow AWS “Web Application Hosting” reference architecture (pdf). This integrates several AWS products:

Amazon S3, used to store the website’s contents
Amazon CloudFront, a CDN improving site performance
Amazon Route53, for managing DNS
Amazon Certificate Manager, for serving content over HTTPS

How it Works

If you are already familiar with static hosting on AWS, feel free to go directly to our examples repository on GitHub, in the aws-ts-static-website folder.

If you are new to AWS, we’ll break down how to configure each component using Pulumi.

Uploading static content to S3

Amazon S3 is a service for storing and retrieving files. This is where we will store the website’s contents, and it is done by just creating an S3 bucket resources and then crawling the www-directory when the Pulumi program executes and creating an S3 bucket object resource for each file.

The main thing to point out here is that we set the contentType property for each bucket object. This way, the right HTTP headers are returned so that files are interpreted the right way. (e.g. images are rendered as images.) The process for inferring the MIME type based on file extension is done by the mime NPM package. No need to write the code on your own, rather we can just reuse an existing library - written in a different programming language, no less! - from our TypeScript application.

const contentBucket = new aws.s3.Bucket("contentBucket",
{
...
});
...
const webContentsRootPath = path.join(process.cwd(), config.pathToWebsiteContents);
crawlDirectory(
webContentsRootPath,
(filePath: string) => {
const relativeFilePath = filePath.replace(webContentsRootPath + "/", "");
const contentFile = new aws.s3.BucketObject(
relativeFilePath,
{
key: relativeFilePath,
acl: "public-read",
bucket: contentBucket,
contentType: mime.getType(filePath) || undefined,
source: new pulumi.asset.FileAsset(filePath),
},
{
parent: contentBucket,
});
});

With the S3 bucket populated with the website’s contents, we need to be able to serve it.

S3 supports the ability to serve a website directly, but S3 when used alone doesn’t support serving the content over HTTPS. Also, by serving the content via a content distribution network, like Amazon CloudFront, content can be served much faster by caching resources across the world. Rather than requiring every web request to go directly to the source S3 bucket.

Setting up a CloudFront CDN backed by S3

There are a lot of details to configuring a CloudFront distribution, from caching policies to rendering custom error pages. While some of these details cannot be avoided, Pulumi programs being just code, allows for using using constants like tenMinutes rather than the number 600.

const distributionArgs: aws.cloudfront.DistributionArgs = {
enabled: true,
aliases: [ config.targetDomain ],
...
// A CloudFront distribution can configure different cache behaviors based on the request path.
// Here we just specify a single, default cache behavior which is just read-only requests to S3.
defaultCacheBehavior: {
targetOriginId: contentBucket.arn,
viewerProtocolPolicy: "redirect-to-https",
allowedMethods: ["GET", "HEAD", "OPTIONS"],
cachedMethods: ["GET", "HEAD", "OPTIONS"],
forwardedValues: {
cookies: { forward: "none" },
queryString: false,
},
minTtl: 0,
defaultTtl: tenMinutes,
maxTtl: tenMinutes,
},
...
};

Attaching it to a domain via Route53

Finally, we hook up our domain to the CloudFront distribution. We just create an alias (A) record that aliases our own domain (e.g. www.pulumi.com) to the CloudFront distribution (e.g. dhy4niicdm7ba.cloudfront.net).

There is a little extra processing we need to do to get the Amazon Route53 Hosted Zone ID for the domain. But we can do that directly in the Pulumi program, and taking advantage of TypeScript’s async/await support.

// Creates a new Route53 DNS record pointing the domain to the CloudFront distribution.
async function createAliasRecord(
targetDomain: string, distribution: aws.cloudfront.Distribution): Promise {
const domainParts = getDomainAndSubdomain(targetDomain);
const hostedZone = await aws.route53.getZone({ name: domainParts.parentDomain });
return new aws.route53.Record(
targetDomain,
{
name: domainParts.subdomain,
zoneId: hostedZone.zoneId,
type: "A",
aliases: [
{
name: distribution.domainName,
zoneId: distribution.hostedZoneId,
evaluateTargetHealth: true,
},
],
});
}
const aRecord = createAliasRecord(config.targetDomain, cdn);

When the Pulumi program is run, the DNS record is created and after a few minutes to allow for worldwide propagation, the website is live. No need to manually log into the AWS console, enter various DNS records, etc. You can create and populate the S3 bucket, setup the CloudFront CDN, and attach it to Route53 all within the same Pulumi program.

Wrapping Up

With around 200 lines of code we were able to integrate four different AWS products using Pulumi to host a static website, served over HTTPS and from a world-wide CDN. Of course there are other ways to host static websites too, and some products or services can do all of that without needing any code at all.

But the benefit of using Pulumi for this is that you are in control of your infrastructure. If later you need to add more functionality, e.g. require authentication or serving some routes dynamically, you can just write a little more code to configure CloudFront. If you wanted to setup a testing or staging environment on a different domain, that would just be a matter of running the same Pulumi program in a different stack.

Pulumi opens up a lot of possibilities and we are excited to see what sorts of things people build using it. If you are interested in using Pulumi for more sophisticated website hosting, or just have questions about serving static files like described here, feel free to ask away on our Pulumi Community Slack.

Pulumi Blog: Typescript

Incident Response as Code: Managing PagerDuty with Pulumi

What you are building

Prerequisites

The provider and the token

Teams, users, and memberships

A schedule people can live with

The escalation policy

The service

The payoff: the alarm and the pager in one program

Azure and Google Cloud, same trick

Breaking a Fargate payment service on purpose

Growing without the drift: a reusable component

Importing what you already clicked together

Conclusion

Fully Automated AI Inference on AWS, Azure, and Google Cloud with Pulumi

What you are building

Prerequisites

Credentials without the copy-paste

One cloud-init, three clouds

The programs

Deploying

Testing the inference server

Cost

Security considerations

What’s next?

Conclusion

Deploy a Private Hermes Agent on Render Securely with Pulumi, Modal, and Tailscale

What is Hermes?

Prerequisites

Understanding the Hermes architecture

Setting up ESC for secrets management

Generating the Render SDK

Securing with Tailscale

Deploying the agent

The complete program

Cost

Running the deployment

Access the agent

Verify the deployment (optional)

Security considerations

What’s next?

Conclusion

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

Deploy OpenClaw on AWS or Hetzner Securely with Pulumi and Tailscale

What is OpenClaw?

Prerequisites

Understanding OpenClaw architecture

Setting up ESC for secrets management

Securing with Tailscale

Deploying to AWS

The Pulumi program

Deploying to Hetzner

The Hetzner Pulumi program

Cost comparison

Running the deployment

Automated onboarding

Access the web UI

Verify the deployment (optional)

Test your assistant

Security considerations

What’s next?

Conclusion

How Ralph Wiggum Built a Serverless SaaS with Pulumi

The problem with AI coding assistants

What if we just do not let it stop?

How the Ralph loop works

Why Pulumi is perfect for Ralph

The experiment

1. Update `Pulumi.yaml`

2. Update `tsconfig.json`

Realizing values using the `apply` function

Example: Using `apply` to Base64 encode an Output

Step 4: Configure VS Code `launch.json` and `tasks.json`