Pulumi Blog: Cloudflare

Cloudflare-First Networking as Code with Pulumi

Pablo Seibelt — Tue, 23 Jun 2026 00:00:00 +0000

Platform teams managing multi-cloud applications face a dangerous visibility gap. While origin infrastructure is tightly controlled, the edge configuration often drifts through manual console tweaks. DNS records point to stale origins, WAF rules are inconsistent across environments, and Zero Trust policies fail to keep pace with team changes. This edge drift leads to application exposure or routing failures that origin teams only notice after users report them.

As applications span multiple clouds, the edge often becomes the most consistent layer for enforcing security and traffic policies. The cost of waiting for a unified edge strategy is high. Every manual change is a potential security hole or a performance bottleneck that bypasses your standard CI/CD rigor.

What you’ll build

In this post, you will build a standardized Cloudflare edge baseline. You’ll use Pulumi to define:

DNS records to point to your multi-cloud origins.
WAF custom rules to block malicious traffic before it hits your network.
A Worker canary to handle edge logic and header validation.
Zero Trust Access policies to secure internal tools and origin access.

By the end, you will have a version-controlled edge that you can validate and deploy across any environment.

The Pulumi program

We’ll build a Pulumi program that sets up a complete edge environment. This approach ensures that your edge security and routing are always in sync with your application code.

Setting up the provider

First, ensure you have the @pulumi/cloudflare package installed and your credentials configured. The examples below are checked against @pulumi/cloudflare@6.15.0, the current v6 Pulumi Registry API at the time of writing.

npm install @pulumi/cloudflare@6.15.0
pulumi config set --secret cloudflare:apiToken "$CLOUDFLARE_API_TOKEN"

Defining the infrastructure

Here is the complete Pulumi program in TypeScript. If your zone already has a custom WAF ruleset for the same phase, import that ruleset or add the rule to your existing ruleset instead of creating another phase-level ruleset that may fail or conflict.

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

const accountId = "<your-cloudflare-account-id>";
const trustedAdminIp = "198.51.100.10";

const zone = new cloudflare.Zone("my-zone", {
 account: {
 id: accountId,
 },
 name: "example.com",
});

const www = new cloudflare.DnsRecord("www", {
 zoneId: zone.id,
 name: "www",
 content: "1.2.3.4",
 ttl: 1,
 type: "A",
 proxied: true,
});

const admin = new cloudflare.DnsRecord("admin", {
 zoneId: zone.id,
 name: "admin",
 content: "1.2.3.4",
 ttl: 1,
 type: "A",
 proxied: true,
});

const wafRule = new cloudflare.Ruleset("waf-rule", {
 zoneId: zone.id,
 name: "Block suspicious traffic",
 description: "Custom WAF rule to block specific patterns",
 kind: "zone",
 phase: "http_request_firewall_custom",
 rules: [{
 action: "block",
 expression: `(http.request.uri.path contains "/admin" and not ip.src in {${trustedAdminIp}})`,
 description: "Block unauthorized admin access",
 }],
});

const worker = new cloudflare.WorkersScript("canary-worker", {
 accountId: accountId,
 scriptName: "edge-canary",
 compatibilityDate: "2026-01-01",
 mainModule: "worker.js",
 content: `
 export default {
 async fetch(request) {
 return new Response("Edge Baseline Validated", {
 headers: { "x-edge-baseline": "active" },
 });
 },
 };
 `,
});

const workerRoute = new cloudflare.WorkersRoute("canary-route", {
 zoneId: zone.id,
 pattern: "www.example.com/*",
 script: worker.scriptName,
});

const adminGroup = new cloudflare.ZeroTrustAccessGroup("admin-group", {
 accountId: accountId,
 name: "Administrators",
 includes: [{
 email: {
 email: "admin@example.com",
 },
 }],
});

const accessApp = new cloudflare.ZeroTrustAccessApplication("internal-tool", {
 accountId: accountId,
 name: "Internal Admin Tool",
 domain: "admin.example.com",
 type: "self_hosted",
 policies: [{
 name: "Allow administrators",
 precedence: 1,
 decision: "allow",
 includes: [{
 group: {
 id: adminGroup.id,
 },
 }],
 }],
});

Validation

Once you run pulumi up, you can validate your edge baseline with these steps:

DNS check: Run dig www.example.com to confirm the record points to Cloudflare’s proxied IPs.
WAF test: Attempt to access www.example.com/admin from an unauthorized IP and verify you receive a 403 Forbidden response.
Worker canary: Use curl -I https://www.example.com and check for the x-edge-baseline: active header.
Access policy: Navigate to admin.example.com and verify you are redirected to the Cloudflare Access login page.

By managing these resources as code, you eliminate the risk of manual drift and ensure that every environment starts with a secure, validated edge baseline.

Deploying a URL Shortener with Cloudflare Workers

David Flanagan — Wed, 29 Jun 2022 23:00:09 +0100

Cloudflare Workers provides a serverless execution environment that allows you to create entirely new applications or augment existing ones without configuring or maintaining infrastructure. They support NodeJS and WebAssembly (WASM), as well as any language that can compile to WASM.

Delivered from over 250 locations worldwide, Cloudflare could be the best way to bring down that latency that’s plaguing your customers. Claiming 0ms for cold starts, automatic scaling, 100k free requests per day, and edge storage built-in: Cloudflare offers a pretty compelling edge compute platform for serverless workloads.

Let’s see how we can deploy a low-latency serverless URL shortener to Cloudflare Workers with Pulumi.

Setting Up

You’ll need a Pulumi project setup with the Cloudflare package added to your Pulumi project and an API token configured.

pulumi new typescript
npm install @pulumi/cloudflare

pulumi new python
pip install pulumi-cloudflare

pulumi new go
go get github.com/pulumi/pulumi-cloudflare/sdk/v4/go/...

pulumi new yaml

Now that we’ve added the package, we need to configure it. You’ll need your Cloudflare accountId and an API Token. The permissions you need for the API token are:

All Accounts
- Workers Tail:Read
- Workers Scripts:Edit
- Account Settings:Read
All Zones
- Zone Settings:Edit
- Zone:Edit
- Workers Routes:Edit
- SSL and Certificates:Edit
- DNS:Edit
All Users
- User Details:Read

You can reduce the scope of “All Zones”, but this means you cannot create a Zone with Pulumi and instead would need to use getZone, described below.

pulumi config set --secret cloudflare:apiToken
pulumi config set cloudflare:accountId

Our URL Shortener

We’re going to use plain old JavaScript for our worker code, as this means we don’t need to transpile anything down. Our URL Shortener will store domains, short tokens, and long URLs in a JavaScript object. We’ll also provide a DEFAULT_URL in-case we can’t match the path requested.

We need to keep our worker source code separate from our Pulumi code, so we’ll be keeping this contained within a file called worker.js.

// worker.js
const DEFAULT_URL = "https://youtube.com/pulumitv"

const redirects = {
 "pulumi.tv": {
 "modern-infrastructure": {
 to: "https://www.youtube.com/playlist?list=PLyy8Vx2ZoWloyj3V5gXzPraiKStO2GGZw"
 }
 },
};

addEventListener("fetch", async (event) => {
 event.respondWith(handleRequest(event.request));
});

async function handleRequest(request) {
 const requestUrl = new URL(request.url);
 const domain = requestUrl.host;
 const path = requestUrl.pathname.substring(1);

 console.log(`Handling request on domain ${domain} for ${path}`);

 if (!(domain in redirects)) {
 console.log(`Domain '${domain}' not found`);
 return Response.redirect(DEFAULT_URL);
 }

 if (path === "") {
 return Response.redirect(DEFAULT_URL);
 }

 const paths = redirects[domain];

 if (path in paths) {
 console.log(`Redirecting too ${paths[path].to}`);
 return Response.redirect(paths[path].to);
 }

 console.log(`Path '${path}' not found`);
 return Response.redirect(DEFAULT_URL);
}

Deploying Our Worker

Now on to our Pulumi code. We need to read our JavaScript code and send it to Cloudflare Workers via the WorkerScript resource.

// index.ts
import * as cloudflare from "@pulumi/cloudflare";
import * as fs from "fs";

const worker = new cloudflare.WorkerScript(
 "url-shortener",
 {
 name: "url-shortener",
 content: fs.readFileSync("worker.js").toString(),
 },
);

# __main__.py
import pulumi
import pulumi_cloudflare as cloudflare

worker_script_file = open("worker.js", "r")
worker_script = worker_script_file.read()
worker_script_file.close()

worker = cloudflare.WorkerScript("url-shortener",
 name="url-shortener",
 content=worker_script)

// main.go
package main

import (
 "fmt"
 "io/ioutil"

 "github.com/pulumi/pulumi-cloudflare/sdk/v4/go/cloudflare"
 "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
 pulumi.Run(func(ctx *pulumi.Context) error {
 workerScriptFile, err := ioutil.ReadFile("worker.js")
 if err != nil {
 log.Fatal(err)
 }
 workerScript := string(workerScriptFile)

 worker, err := cloudflare.NewWorkerScript(ctx, "url-shortener", &cloudflare.WorkerScriptArgs{
 Content: pulumi.String(workerScript),
 Name: pulumi.String("links"),
 }, pulumi.Protect(true))
 if err != nil {
 return err
 }
 return nil
 })
}

# Pulumi.yaml
name: url-shortener
runtime: yaml
description: url-shortener in Pulumi YAML
variables:
 workerScript:
 Fn::ReadFile: ./worker.js
resources:
 worker:
 type: cloudflare:index:WorkerScript
 properties:
 name: url-shortener
 content: ${workerScript}

Where’s the Types?!

If you wanted to use TypeScript for the worker code for some guarantees around the short/long URL objects, you can definitely do so. This does require an additional step to transpile the TypeScript to JavaScript though. Remember to update the Pulumi code to read the ts extension.

// worker.ts
interface Redirect {
 to: string;
}

interface Redirects {
 [domain: string]: {
 [path: string]: Redirect;
 };
}

const redirects: Redirects = {
 "pulumi.tv": {
 "/": {
 to: "https://youtube.com/pulumitv",
 },
 "modern-infrastructure": {
 to: "https://www.youtube.com/playlist?list=PLyy8Vx2ZoWloyj3V5gXzPraiKStO2GGZw"
 }
 },
};

You’ll also need a tsconfig.json:

{
 "compilerOptions": {
 "experimentalDecorators": true,
 "forceConsistentCasingInFileNames": true,
 "lib": ["ES2020"],
 "module": "ES2020",
 "moduleResolution": "node",
 "noFallthroughCasesInSwitch": true,
 "noImplicitReturns": true,
 "outDir": "dist",
 "pretty": true,
 "sourceMap": true,
 "strict": true,
 "target": "ES2020",
 "outDir": "dist",
 "types": ["@cloudflare/workers-types"]
 },
 "include": ["index.ts"]
}

Then we can transpile the code with a local.Command resource.

We need to add our command package and then add a local command to our code.

npm install @pulumi/command

// index.ts
import * as command from "@pulumi/command";

const compileWorker = new command.local.Command("compile-worker", {
 create:
 "yarn run tsc >/dev/null && cat ./dist/index.js",
 dir: "../worker",
});

You could then use the stdout output, compileWorker.stdout, from our local command resource for the content input on the WorkerScript resource, instead of fs.readFileSync.

pip install pulumi_command

# __main__.py
import pulumi_command as command

compile_worker = command.local.Command('compile-worker', create='yarn run tsc >/dev/null && cat ./dist/index.js')

You could then use the stdout output, compile_worker.stdout, from our local command resource for the content input on the WorkerScript resource, instead of open and read on the file.

go get github.com/pulumi/pulumi-command/sdk/go/...

// main.go
import (
 "github.com/pulumi/pulumi-command/sdk/go/command/local"
)

compileWorker, err := local.NewCommand(ctx, "compile-worker", &local.CommandArgs{
 Create: pulumi.String("yarn run tsc >/dev/null && cat ./dist/index.js"),
})

if err != nil {
 return err
}

You could then use the stdout output, compileWorker.Stdout, from our local command resource for the content input on the WorkerScript resource, instead of ioutil.ReadFile.

# Pulumi.yaml
resources:
 compileWorker:
 type: command:local:Command
 properties:
 create: yarn run tsc >/dev/null && cat ./dist/index.js

You could then use the stdout output, ${compileWorker.stdout}, from our local command resource for the content input on the WorkerScript resource, instead of Fn:ReadFile.

Hooking Up a Domain

Cloudflare Workers allow us to connect a domain name, instead of using the generated workers.dev subdomain. To do so with Pulumi, we need to create or fetch a Cloudflare Zone.

Create a Zone(s)

Once we create the cloudflare.Zone resource, we also need to create a cloudflare.ZoneSettingsOverride resource to ensure that we enable:

alwaysUseHttps: "on"
automaticHttpsRewrites: "on"
ssl: "strict"
universalSsl: "on".

Without these settings, our traffic will be available over HTTP and … come on, it’s 2022 already.

// index.ts
const zone = new cloudflare.Zone("pulumi.tv", {
 zone: "pulumi.tv",
 plan: "free",
});

const zoneSettings = new cloudflare.ZoneSettingsOverride("pulumi.tv", {
 zoneId: z.id,
 settings: {
 alwaysUseHttps: "on",
 automaticHttpsRewrites: "on",
 ssl: "strict",
 minTlsVersion: "1.2",
 universalSsl: "on",
 },
});

# __main__.py
zone = cloudflare.Zone("pulumi.tv", zone="pulumi.tv", plan="free")
zone_settings = cloudflare.ZoneSettingsOverride(
 "pulumi.tv",
 zone_id=zone.id,
 settings=cloudflare.ZoneSettingsOverrideSettingsArgs(
 always_use_https="on",
 automatic_https_rewrites="on",
 ssl="strict",
 min_tls_version="1.2",
 universal_ssl="on",
 ),
)

// main.go
zone, err := cloudflare.NewZone(ctx, "pulumi.tv", &cloudflare.ZoneArgs{
 Zone: pulumi.String("pulumi.tv"),
 Plan: pulumi.String("free"),
})
if err != nil {
 return err
}

_, err = cloudflare.NewZoneSettingsOverride(ctx, "pulumi.tv", &cloudflare.ZoneSettingsOverrideArgs{
 ZoneId: zone.ID(),
 Settings: &cloudflare.ZoneSettingsOverrideSettingsArgs{
 AlwaysUseHttps: pulumi.String("on"),
 AutomaticHttpsRewrites: pulumi.String("on"),
 UniversalSsl: pulumi.String("on"),
 Ssl: pulumi.String("strict"),
 MinTlsVersion: pulumi.String("1.2"),
 },
})
if err != nil {
 return err
}

# Pulumi.yaml
resources:
 zone:
 type: cloudflare:index:Zone
 properties:
 zone: pulumi.tv
 plan: free
 zoneSettings:
 type: cloudflare:index:ZoneSettingsOverride
 properties:
 zoneId: ${zone.id}
 settings:
 alwaysUseHttps: "on"
 automaticHttpsRewrites: "on"
 universalSsl: "on"
 ssl: "strict"
 minTlsVersion: "1.2"

Fetch a Zone

// index.ts
const zone = await cloudflare.getZone({
 name: "pulumi.tv",
});

# __main__.py
zone = cloudflare.get_zone(name="pulumi.tv")

// main.go
zone, err := cloudflare.LookupZone(ctx, &cloudflare.LookupZoneArgs{
 Name: pulumi.String("pulumi.tv"),
})

# Pulumi.yaml
variables:
 zoneId:
 Fn::Invoke:
 Function: cloudflare:index:getZone
 Arguments:
 name: pulumi.tv
 Return: id
 zoneName:
 Fn::Invoke:
 Function: cloudflare:index:getZone
 Arguments:
 name: pulumi.tv
 Return: name

Creating the Routes

In-order to actually send traffic to our workers from these zones, we need to setup the DNS records and create the routes. While Cloudflare does provide a web UI to “connect” a custom domain, in beta, this isn’t yet available over the Cloudflare API.

Instead, we need to use a proxied DNS record on a subdomain, or domain apex, that points to workers.dev.

// index.ts
const record = new cloudflare.Record(
 "pulumi.tv",
 {
 zoneId: zone.id,
 name: "@",
 type: "CNAME",
 value: "workers.dev",
 proxied: true,
 },
 {
 deleteBeforeReplace: true,
 }
);

const route = new cloudflare.WorkerRoute(
 "pulumi.tv",
 {
 zoneId: zone.id,
 pattern: pulumi.interpolate`${zone.zone}/*`,
 scriptName: worker.name,
 }
);

# __main__.py
from pulumi import Output

record = cloudflare.Record("pulumi.tv",
 name="@", zone_id=zone.id, type="CNAME", value="workers.dev")

route = cloudflare.WorkerRoute("pulumi.tv", zone_id=zone.id, pattern=Output.concat(zone.zone, "/*"), script_name=worker.name)

// main.go
_, err = cloudflare.NewRecord(ctx, "pulumi.tv", &cloudflare.RecordArgs{
 Name: pulumi.String("@"),
 ZoneId: zone.ID(),
 Type: pulumi.String("CNAME"),
 Value: pulumi.String("workers.dev"),
})
if err != nil {
 return err
}

_, err = cloudflare.NewWorkerRoute(ctx, "pulumi.tv", &cloudflare.WorkerRouteArgs{
 ZoneId: zone.ID(),
 Pattern: pulumi.Sprintf("%s/*", zone.Zone),
 ScriptName: worker.Name,
})
if err != nil {
 return err
}

# Pulumi.yaml
resources:
 record:
 type: cloudflare:index:Record
 properties:
 name: "@"
 zoneId: ${zone.id}
 type: CNAME
 value: workers.dev
 route:
 type: cloudflare:index:WorkerRoute
 properties:
 # If you fetched a Zone, this would be ${zoneId}
 zoneId: ${zone.id}
 # If you fetched a Zone, this would be ${zoneName}
 pattern: ${zone.zone}/*
 scriptName: ${worker.name}

Fin

Lastly, we can run pulumi up and run a curl 😀

❯ pulumi up

 Type Name Status
 + pulumi:pulumi:Stack short-links-production created
 + ├─ cloudflare:index:Zone pulumi.tv created
 + ├─ cloudflare:index:WorkerScript links created
 + ├─ cloudflare:index:ZoneSettingsOverride pulumi.tv created
 + ├─ cloudflare:index:Record pulumi.tv created
 + └─ cloudflare:index:WorkerRoute pulumi.tv created

Resources:
 + 7 created

Duration: 27s

❯ curl -I https://pulumi.tv
HTTP/2 302
date: Wed, 29 Jun 2022 21:57:20 GMT
location: https://youtube.com/pulumitv

❯ curl -I https://pulumi.tv/modern-infrastructure
HTTP/2 302
date: Wed, 29 Jun 2022 21:57:20 GMT
location: https://www.youtube.com/playlist?list=PLyy8Vx2ZoWloyj3V5gXzPraiKStO2GGZw

That’s it! Deploying your own URL Shortener with some JavaScript and Cloudflare Workers with Pulumi.

Complete Code

// index.ts
import * as pulumi from "@pulumi/pulumi";
import * as cloudflare from "@pulumi/cloudflare";
import * as fs from "fs";


const zone = new cloudflare.Zone("pulumi.tv", {
 "pulumi.tv",
 plan: "free",
});

const zoneSettings = new cloudflare.ZoneSettingsOverride("pulumi.tv", {
 zoneId: zone.id,
 settings: {
 alwaysUseHttps: "on",
 automaticHttpsRewrites: "on",
 ssl: "strict",
 minTlsVersion: "1.2",
 universalSsl: "on",
 },
});

const worker = new cloudflare.WorkerScript(
 "pulumi.tv",
 {
 name: "pulumi.tv",
 content: fs.readFileSync("worker.js").toString(),
 }
);

const record = new cloudflare.Record(
 "pulumi.tv",
 {
 zoneId: zone.id,
 name: "@",
 type: "CNAME",
 value: "workers.dev",
 proxied: true,
 },
 {
 deleteBeforeReplace: true,
 }
);

const workerRoute = new cloudflare.WorkerRoute(
 "pulumi.tv",
 {
 zoneId: zone.id,
 pattern: pulumi.interpolate`${zone.zone}/*`,
 scriptName: worker.name,
 }
);

# __main__.py
import pulumi
from pulumi import Output
import pulumi_cloudflare as cloudflare

worker_script_file = open("worker.js", "r")
worker_script = worker_script_file.read()
worker_script_file.close()

worker = cloudflare.WorkerScript("url-shortener", name="url-shortener", content=worker_script)

zone = cloudflare.Zone("pulumi.tv", zone="pulumi.tv", plan="free")
zone_settings = cloudflare.ZoneSettingsOverride(
 "pulumi.tv",
 zone_id=zone.id,
 settings=cloudflare.ZoneSettingsOverrideSettingsArgs(
 always_use_https="on",
 automatic_https_rewrites="on",
 ssl="strict",
 min_tls_version="1.2",
 universal_ssl="on",
 ),
)

record = cloudflare.Record("pulumi.tv",
 name="@", zone_id=zone.id, type="CNAME", value="workers.dev")

route = cloudflare.WorkerRoute("pulumi.tv", zone_id=zone.id, pattern=Output.concat(zone.zone, "/*"), script_name=worker.name)

// main.go
package main

import (
 "io/ioutil"
 "log"

 "github.com/pulumi/pulumi-cloudflare/sdk/v4/go/cloudflare"
 "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
 pulumi.Run(func(ctx *pulumi.Context) error {
 workerScriptFile, err := ioutil.ReadFile("worker.js")
 if err != nil {
 log.Fatal(err)
 }
 workerScript := string(workerScriptFile)

 worker, err := cloudflare.NewWorkerScript(ctx, "url-shortener", &cloudflare.WorkerScriptArgs{
 Content: pulumi.String(workerScript),
 Name: pulumi.String("links"),
 }, pulumi.Protect(true))
 if err != nil {
 return err
 }

 zone, err := cloudflare.NewZone(ctx, "pulumi.tv", &cloudflare.ZoneArgs{
 Zone: pulumi.String("pulumi.tv"),
 Plan: pulumi.String("free"),
 })
 if err != nil {
 return err
 }

 _, err = cloudflare.NewZoneSettingsOverride(ctx, "pulumi.tv", &cloudflare.ZoneSettingsOverrideArgs{
 ZoneId: zone.ID(),
 Settings: &cloudflare.ZoneSettingsOverrideSettingsArgs{
 AlwaysUseHttps: pulumi.String("on"),
 AutomaticHttpsRewrites: pulumi.String("on"),
 UniversalSsl: pulumi.String("on"),
 Ssl: pulumi.String("strict"),
 MinTlsVersion: pulumi.String("1.2"),
 },
 })
 if err != nil {
 return err
 }

 _, err = cloudflare.NewRecord(ctx, "pulumi.tv", &cloudflare.RecordArgs{
 Name: pulumi.String("@"),
 ZoneId: zone.ID(),
 Type: pulumi.String("CNAME"),
 Value: pulumi.String("workers.dev"),
 })
 if err != nil {
 return err
 }

 _, err = cloudflare.NewWorkerRoute(ctx, "pulumi.tv", &cloudflare.WorkerRouteArgs{
 ZoneId: zone.ID(),
 Pattern: pulumi.Sprintf("%s/*", zone.Zone),
 ScriptName: worker.Name,
 })
 if err != nil {
 return err
 }

 return nil
 })
}

# Pulumi.yaml
name: url-shortener
runtime: yaml
description: url-shortener in Pulumi YAML
variables:
 workerScript:
 Fn::ReadFile: ./worker.js
resources:
 worker:
 type: cloudflare:index:WorkerScript
 properties:
 name: url-shortener
 content: ${workerScript}
 zone:
 type: cloudflare:index:Zone
 properties:
 zone: rawkoded.link
 plan: free
 zoneSettings:
 type: cloudflare:index:ZoneSettingsOverride
 properties:
 zoneId: ${zone.id}
 settings:
 alwaysUseHttps: "on"
 automaticHttpsRewrites: "on"
 universalSsl: "on"
 ssl: "strict"
 minTlsVersion: "1.2"
 record:
 type: cloudflare:index:Record
 properties:
 name: "@"
 zoneId: ${zone.id}
 type: CNAME
 value: workers.dev
 route:
 type: cloudflare:index:WorkerRoute
 properties:
 zoneId: ${zone.id}
 pattern: ${zone.zone}/*
 scriptName: ${worker.name}

Managing my DNS with Pulumi

David Flanagan — Tue, 29 Mar 2022 10:00:00 +0000

Managing DNS records efficiently is crucial for anyone who owns multiple domains. Whether you’re handling infrastructure for a business, securing brand assets, or just keeping personal projects organized, having a structured approach to DNS management can save time and prevent headaches.

With Pulumi, you can automate DNS configuration, ensure consistency across providers, and make changes programmatically—reducing manual work and human error. In this post, we’ll walk through how to use Pulumi to manage DNS records dynamically and effectively.

Overview

Using Pulumi’s ComponentResource API, we’re able to provide a nice developer experience for manipulating DNS records through methods on an object—we call this object the “Domain Controller.” I have a domain controller for every domain that I own. Through this controller I can add DNS records through helper methods that keep the interface as simple as can be.

So, let’s explore this. First, I’ll show you the consumer API and how you work with the Controller, then I’ll show you how it was put together.

Fetching the Controller

First, we need to request a controller for our domain name we want to manipulate. This creates a new object based on our Controller class.

const rawkodeDev = new Controller("rawkode.dev");

Creating Records

Now that we have a controller for the rawkode.dev domain, we can start to add records. As with pretty much every domain, there’s a selection of things required out of the box:

MX records for email configuration
- or an SPF record to note that the domain will not be used for email
TXT records for dmarc and other verification purposes
A/CNAME records for any subdomains in-use

Configuring Apex

My website is delivered via Vercel, so I need an A record configured with their BGP-advertised ingress address. While I prefer to host my website as no-www, I do create a www record to redirect as required.

zone.createRecord("@", "A", ["76.76.21.21"]);
zone.createRecord("www", "CNAME", [`${DOMAIN}`]);

Configuring for Email

I typically use GSuite for any of my domains that have email configured. The domain controller class we extend provides a createMxRecord method. We explicitly separate this from createRecord because we need some conveniences, such as a unique name for each record when there are multiple with the same priority.

zone.createMxRecord("@", 1, "aspmx.l.google.com");
zone.createMxRecord("@", 5, "alt1.aspmx.l.google.com");
zone.createMxRecord("@", 5, "alt2.aspmx.l.google.com");
zone.createMxRecord("@", 10, "alt3.aspmx.l.google.com");
zone.createMxRecord("@", 10, "alt4.aspmx.l.google.com");

If we don’t want email active for this domain, then we can also disable it:

zone.disableEmail();

Where is my DNS?

The thing I love about this approach is that you’ve no idea where I host my DNS. That’s intentional. It’s not important when I’m configuring records on my domains. In fact, I’ve moved my DNS several times over the last 18 months, and it’s required very little change to my code, requiring only trivial changes to the underlying Controller. I like that.

For the record, I’m currently using Cloudflare; though I have used DNSimple, Route53, Google Cloud DNS, and others. I like to experiment. 😅

How Does it Work?

We’re going to dive into this Controller class in a bit more detail, but if you’d prefer to see my real-world code, check it out here.

The first thing we need for our Controller is a skeleton of a ComponentResource.

import { ComponentResource } from "@pulumi/pulumi";

export class Controller extends ComponentResource {
}

I have a few properties on this class that allow us to track some internal state, such as:

readonly domainName: string;
readonly zone: cloudflare.Zone;
private emailDisabled: boolean = false;
private records: cloudflare.Record[];
private mxCounter = 0;

Quickly followed by the constructor that is responsible for creating the zone on our DNS provider and instantiating some of these initial properties:

constructor(domainName: string) {
 super(`rawkode:DnsController`, `${domainName}`);

 this.domainName = domainName;
 this.records = [];

 this.zone = new cloudflare.Zone(
 domainName,
 {
 zone: domainName,
 type: "full",
 plan: "free",
 },
 {
 protect: true,
 parent: this,
 }
 );
}

Let’s jump to something a bit more useful and look at record creation.

public createRecord(name: string, type: string, values: string[]): void {
 values.forEach((value, index) => {
 const record = new cloudflare.Record(
 this.resourceName(`${name}-${index}`, type),
 {
 zoneId: this.zone.id,
 name: this.recordName(name),
 ttl: 300,
 type,
 value,
 },
 { parent: this.zone, protect: false, deleteBeforeReplace: true }
 );

 this.records.push(record);
 });

 return;
}

This function really only creates a new cloudflare.Record, but because we’re using a ComponentResource, we can also leverage internal/private functions that remove duplication from our code and help us keep things DRY (Don’t Repeat Yourself).

There are two examples above:this.resourceName(${name}-${index}, type) and name: this.recordName(name),. We have two functions, resourceName() and recordName() that help sanitize some of our inputs.

First, resourceName gives us a uniquely namespaced (by domain name) resource name for Pulumi. It has “DNS-knowledge” that if there’s no subdomain name or we’re using DNS notation of “@” for “root”, that this should be named as such. We also include the record type into the name to allow multiple records on subdomains when the type is different, such as TXT and MX records. We pretty much do the same for recordName, only it returns a FQDN. ComponentResources are amazing for encapsulating this type of internal knowledge into the resource and away from the consumer.

private resourceName(name: string, type: string): string {
 if (name.length == 0) {
 return `${this.domainName}-${type}`;
 }

 if (name == "@") {
 return `${this.domainName}-${type}`;
 }

 return `${this.domainName}-${type}-${name}`;
}

OK. What about email records? Well, let’s take a look at “disabling” email. I’ve said “disabling” because we can’t actually stop people from using the domain when they’re sending spammy emails, but the SPF record should provide enough knowledge to email companies that email shouldn’t be expected from this domain.

The first thing we do inside disableEmail() is ensure that the consumer hasn’t already set any MX records. If they have, then we’ll issue an error. You can’t configure email AND discourage it at the same time. We then set our boolean value to true, which will be used in our createMxRecord function later. Lastly, we can create the TXT record on our domain that tells Google et al. that email shouldn’t be accepted from this domain.

public disableEmail(): void {
 if (this.mxCounter > 0) {
 throw new Error(
 `Cannot disable email for ${this.domainName} if MX records exist.`
 );
 }

 this.emailDisabled = true;

 this.records.push(
 new cloudflare.Record(
 this.resourceName(`disable-email`, "txt"),
 {
 zoneId: this.zone.id,
 name: "@",
 ttl: 300,
 type: "TXT",
 value: `"v=spf1 -all"`,
 },
 { parent: this.zone, protect: false, deleteBeforeReplace: true }
 )
 );

 return;
}

We’re being good email citizens here. 😃 Let’s take a look at our createMxRecord function.

public createMxRecord(name: string, priority: number, value: string): void {
 if (this.emailDisabled) {
 throw new Error(
 `Cannot add MX records if ${this.domainName} has email disabled.`
 );
 }

 const record = new cloudflare.Record(
 this.resourceName(`${name}-${this.mxCounter++}`, "MX"),
 {
 zoneId: this.zone.id,
 name: this.recordName(name),
 ttl: 300,
 type: "MX",
 priority,
 value,
 },
 { parent: this.zone, protect: false, deleteBeforeReplace: true }
 );

 this.records.push(record);

 return;
}

It’s very similar to our createRecord function, only this one has the emailDisabled check to ensure our consumers don’t try to do the silly thing. We also increment our MX counter to keep track of how many MX records we’ve created, so that records with the same priority can be distinguished and have unique URNs when created.

What’s Next?

I rely on this code a lot, but it’s far from finished. I try to improve it as often as time allowed, and next on my list is to support multiple DNS providers on the controller as well as “alias domains.”

Multiple DNS providers on the controller would allow me to have backup DNS records on another provider in the event that one should be unavailable, or just to allow me to experiment and continue to try other providers without a bigger time commitment.

Alias domains would allow me to stop duplicating a lot of the code I use for domains that share the same behaviors, such as URL shorteners. Instead of:

const rawkodeSh = new Controller("rawkode.sh");
const rawkoDe = new Controller("rawko.de");
const rawkodeLive = new Controller("rawkode.live");

I could hopefully do:

const rawkodeShorts = new Controller("rawko.de", {
 aliasDomains: ["rawkode.sh", "rawkode.live"],
})

Pulumi facilitates all these abstractions that allow us to make our lives easier. This is what I do with my Pulumi programs, but what do you do with yours?