Pulumi Blog: David Flanagan

Deploying Amazon EKS Anywhere on Bare Metal

David Flanagan — Fri, 01 Jul 2022 13:03:41 -0700

Check out version 3.0 of the Pulumi EKS Provider.

Some of the largest and most complex deployments that teams manage are hybrid and multi-cloud deployments. Kubernetes is a common component in these deployments because it enables platform teams to provide a common set of services across cloud and on-premises infrastructure and simplifies the process of migrating and scaling workloads as demand fluctuates. Pulumi simplifies these deployment scenarios but teams often need to manage different flavors of Kubernetes for on-premises deployments versus cloud deployments.

We were excited to support the launch of the Amazon EKS Distro in 2020 as it promised to help customers standardize their Kubernetes version and its dependencies. When EKS Anywhere launched last year, the pieces were starting to fall into place to enable consistent tooling for managing Kubernetes across your datacenter and in any cloud.

How it works (the short version)

AWS has now announced the latest innovation for EKS: Amazon EKS Anywhere Bare Metal and allows EKS Anywhere to be run without the need for VMWare vSphere. EKS Anywhere Bare Metal now enables an automated process to bootstrap provisioning and create the EKS-A control plane and worker nodes. Bare metal servers then PXE boot and run the OS provisioning process by communicating with a Tinkerbell Infrastructure Services Stack. At launch, bare metal servers are provisioned with AWS Bottlerocket with support for Ubuntu OS 20.04 also available.

Here are the current system requirements to run EKS Anywhere Bare Metal:

Cluster Hardware Requirements
- 4 GB of RAM for OSIE/Hook boot and operation
- Capability to netboot using iPXE
Tinkerbell Infrastructure Services Stack Requirements
- CPU - 2vCPUs, RAM - 4 GB, Disk - 20 GB (includes the OS)
- Network - L2 networking is required for the ability to run a DHCP server
- Operating System: Ubuntu 16.04+ and CentOS 7
Operating Systems Supported
- Ubuntu 20.04
- AWS Bottlerocket

Setting up your bare metal servers

As a “born in the cloud” company, Pulumi does not have a data center lying around for testing, so we’ll walk through the process of setting up EKS Anywhere Bare Metal using servers hosted by Equinix Metal. This really shows off the power of running EKS Anywhere and the great lengths the AWS team has gone to in enabling EKS Anywhere for a variety of scenarios.

The process to setup bare metal clusters involves the following steps:

Equinix Metal configuration
eks-a generate hardware config
eks-a generate cluster config
Create a bootstrap cluster on the admin machine
Provision and create control plane bare metal servers
Provision and create bare metal worker nodes
Move cluster management to the workload cluster
Delete the bootstrap cluster

Fortunately, Pulumi components make it easy to automate most of these steps. For example:

import * as eksa from "@pulumiverse/aws-eksa";

const page = new eksa.metal.Cluster("cluster", {
 clusterName: "rawkode",
 metro: "am",
 projectId: "someProjectID",
});

To use the component, take the following steps:

Make sure you’ve followed the steps to setup Pulumi and AWS
Grab the EKS-A component and example code on Pulumiverse.

Set your Equinix Metal Auth token as a Pulumi secret:

pulumi config set --secret equinix-metal:authToken

Run pulumi up.

Your output should look similar to the example below:

Give it a try!

These steps will vary depending on the actual hardware and/or bare metal service you decide to use. Check out our example repo and give it a try for yourself. If you run into any issues, you can reach out to us on Community Slack with your questions on the #aws channel.

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}

Patterns for Drift Detection with Pulumi

David Flanagan — Thu, 16 Jun 2022 09:26:46 -0500

Portions of this blog post are out of date. See the Pulumi Deployments drift detection blog post for an updated overview and examples.

Let’s face it, at some point someone is going to modify your carefully-crafted and automated infrastructure without updating your Pulumi program. These changes cause the desired state of our Pulumi program’s to be inconsistent with the state of the world. These inconsistencies are often referred to as “drift”. In this article, I want to cover a couple of patterns for detecting and reconciling this drift with your Pulumi programs.

Why is Drift Detection Important?

Reconciling drift as quickly as possible is very important in the infrastructure as code (IaC) space because the longer drift is left unattended, the harder it becomes for automation to reconcile in a manner that can be considered safe for your organization, SLAs, and customers happiness. Imagine this as if it were your car. If a single tyre needs replaced, you might be OK for a while and not notice any problems driving. If you leave that unattended and another tyre runs flat, then you’ve got a slightly more serious problem. As these smaller problems accumulate you’re applying a multiplier of risk to your overall infrastructure, especially during reconciliation. The more resources Pulumi needs to handle during this step, the more likely for some collateral damage.

It’s important that you build a system that can tolerate a nominal amount of drift but actively works to repair that as quickly as possible.

Let’s see how.

Refreshing the World

When you run a pulumi up, Pulumi will create a directed-acyclic graph (DAG) from your Pulumi program. This graph is then compared to your state file, and any changes that need to happen to have the DAG match the state file are applied. Pulumi does not reach out to “the world” to detect if what is in your state file is actually still up to date, at-least not without adding the --refresh option.

That’s the secret sauce to ensuring that we can begin to detect and reconcile drift. Of course, this comes with a couple of caveats that you need to be aware of before adopting --refresh as your default behavior.

Firstly, it’s slower. The --refresh option will take longer because the Pulumi program needs to reach out to all of the providers and fetch information on the resources in your state file.

Secondly, the refresh will sync potentially “untracked” fields within your resources and could trigger more updates to your resources than you’ve had previously. This isn’t a bad thing and Pulumi’s defaulting will hopefully ensure that resources aren’t needlessly updated, but it’s definitely worth keeping in mind.

With that being said, let’s take a look at two common strategies for updating Pulumi programs.

Workflow Approach

The most common approach is to use your CI/CD / build system to run Pulumi whenever your source code changes. This works quite well, but it means that any drift isn’t detected and reconciled until someone pushes some changes. If nobody commits to the repository for 2 days, a week, or even longer - then a few problems can arise. The longer the gap, the more chance of drift causing more problems during the next run. Drift can cause resources to be recreated, which may be unexpected, and if left long enough, the “drift” might become expected behavior within your system and the next reconcile becomes a “break”.

When using the workflow approach for your Pulumi program’s, I highly encourage you to schedule builds as frequently as you can. Whether that’s hourly or daily, the more you run your Pulumi and handle drift, the easier and more comfortable you’ll be with the automation.

If you want to do this with GitHub Actions, you can use the cron settings on your workflow. This is an example of my own production infrastructure:

name: infrastructure

on:
 workflow_dispatch: {}
 push:
 branches:
 - main
 schedule:
 - cron: "6 6 * * *"

CircleCI also makes this rather easy too:

 daily-run-workflow:
 triggers:
 - schedule:
 cron: "6 6 * * *"
 filters:
 branches:
 only:
 - main

Operator Approach

Now, scheduled executions are great, but if you want to take that to the next level - using the Pulumi Kubernetes Operator is the next step. The operator can be configured to run every few minutes, ensuring that your world is always consistent with your Pulumi program. Here’s an example YAML representation of a Pulumi stack:

apiVersion: pulumi.com/v1
kind: Stack
metadata:
 name: some-repo-production
spec:
 stack: production
 projectRepo: https://github.com/some/repo
 branch: "refs/heads/main"
 destroyOnFinalize: true
 continueResyncOnCommitMatch: true
 refresh: true
 resyncFrequencySeconds: 60

The last three settings are the most important part of this configuration. Unfortunately, these are not the defaults - but there’s an issue tracking this change.

continueResyncOnCommitMatch is a setting that tells Pulumi to run even though the code itself hasn’t changed, which when used with refresh: true means we’ll always update the state of the world and reconcile any drift. resyncFreqeuncySeconds is the number of seconds between each reconcile.

Making Refresh Your Default

Before you go updating all your workflow files, or adopting the operator, for all the benefits of continuous reconciliation and drift detection, let’s cover a few safety tips.

Always run a pulumi up --refresh locally / manually first and inspect the changes. Pulumi may wish to replace some resources and if you don’t want that to happen - you need to prepare those resources for your new continuous reconciliation.

Protect

If you have a resource that should NEVER be deleted, make sure you protect it. You can do this by adding a ResourceOption to the resource in your Pulumi program.

{
 protect: true
}

opts=ResourceOptions(protect=True)

pulumi.Protect(true)

new CustomResourceOptions { Protect = true }

CustomResourceOptions.builder()
 .protect(true)

options:
 protect: true

Ignore Changes

If Pulumi wants to replace a resource that you don’t believe needs to be updated, you can ask Pulumi to ignoreChanges on certain properties. Of course, it might be best to have your code match those properties, but in the event that you can’t - you can use the code below to ignore:

{
 ignoreChanges: ["prop"]
}

opts=ResourceOptions(ignore_changes=["prop"])

pulumi.IgnoreChanges([]string{"prop"})

new CustomResourceOptions { IgnoreChanges = { "prop" } }

CustomResourceOptions.builder()
 .ignoreChanges("prop")

options:
 ignoreChanges:
 - prop

Delete Before Replace

If you have any resources that don’t use auto-naming, you’ll also need to ensure they have the deleteBeforeReplace option enabled.

{
 deleteBeforeReplace: true
}

opts=ResourceOptions(delete_before_replace=["prop"])

pulumi.DeleteBeforeReplace(true)

new CustomResourceOptions { DeleteBeforeReplace = true }

CustomResourceOptions.builder()
 .deleteBeforeReplace(true)

options:
 deleteBeforeReplace: true

Once you’ve run a couple of pulumi up --refresh and you’re comfortable with the proposed executions, you can adopt the automation and sleep easier, knowing that you’re handling drift and keeping your infrastructure up to date.

Want to See More?

Watch me demo some of these features live, on YouTube, on my PulumiTV series: Modern Infrastructure.

Extending Pulumi's Language Support via YAML

David Flanagan — Wed, 08 Jun 2022 10:56:34 -0500

It’s a surprise to nobody that Pulumi’s YAML support has me rather excited, even though I’m unlikely to use YAML itself for Pulumi. So why do I find it exciting? Well, because it’s an open interface to provide support to many other programming languages for Pulumi.

Let’s take a look at using YAML as a bridge for CUE, JSONNET, and Rust.

CUE

It’s no surprised to anybody that I’m a rather large supporter of the CUE project. I worked hard on the YAML launch to ensure CUE was available, with our CTO Luke covering one of the examples in our release blog. More recently, I also dedicated a Modern Infrastructure to showing how to manage DNS records on Cloudflare with a CUE interface.

I believe that CUE could open up a whole world of possibilities for Pulumi and I’m excited to see what myself and others can come up with in this space in 2022.

To use CUE as a compiler for Pulumi YAML, you need to update the Pulumi.yaml file with the following compiler options:

runtime:
 name: yaml
 options:
 compiler: cue export

Next, run cue mod init to create a new CUE module. From here, you can create any file with a .cue extension and it’ll become part of your Pulumi YAML project.

Here’s a small example:

package pulumi

resources:
 randomPassword: {
 type: "random:RandomPassword"
 properties: {
 length: 16
 special: true
 overrideSpecial: "_%@"
 }
 }

outputs:
 password: "${randomPassword.result}"

JSONNET

In much the same view as CUE, Pulumi YAML can actually be a compilation target for any YAML superset. Let’s take a look at another popular option: JSONNET.

First, we need to configure the compiler options:

runtime:
 name: yaml
 options:
 compiler: jsonnet index.jsonnet

Then we can provide the index.jsonnet file. Here’s the same example as above, but in JSONNET.

{
 resources: {
 randomPassword: {
 type: "random:RandomPassword",
 properties: {
 length: 16,
 special: true,
 overrideSpecial: "_%@"
 }
 }
 }

 outputs: {
 password: "${randomPassword.result}"
 }
}

Now, this is actually just a plain JSON object and we’ve not taken advantage of any JSONNET features yet. So let’s create a function for creating this random resource.

local random_password(length=16, special=true, overrideSpecial="@") = {
 type: "random:RandomPassword",
 properties: {
 length: length,
 special: special,
 overrideSpecial: overrideSpecial,
 },
};


local first = random_password();
local second = random_password();

{
 resources: {
 first: first,
 second: second,
 },

 outputs: {
 "firstPassword": "first.result"
 }
}

Now we have a function for creating a resource, with default values. Nice.

Rust

So, what if we wanted to do the same … but with Rust? Let’s see! First, our compiler options:

runtime:
 name: yaml
 options:
 compiler: cargo run

Next, we need to generate some Rust types to represent our Pulumi resources. Instead of doing the random resource, like above, let’s go with the Cloudflare resources from the YouTube video I recorded.

use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
pub struct Zone {
 pub zone: String,
}

#[derive(Serialize, Deserialize)]
pub struct Record {
 pub name: String,
 pub typ: String,
 pub value: String,
}

Rust has great meta programming capabilities, meaning our types can all be enriched by Serde to handle serialization through simple derive macros.

Next, we spec out some skeleton Pulumi types too:

use crate::cloudflare::{Record, Zone};
use serde::{Deserialize, Serialize};
use std::collections::HashMap;

#[derive(Serialize, Deserialize)]
pub struct Pulumi {
 pub resources: HashMap<String, Resource>,
}

#[derive(Serialize, Deserialize)]
#[serde(tag = "type")]
pub enum Resource {
 #[serde(rename = "cloudflare:Zone")]
 Zone { properties: Zone },
 #[serde(rename = "cloudflare:Record")]
 Record { properties: Record },
}

We represent all the “available” resources via the Resource enum, which has a special annotation to indicate the “type” for Pulumi. We also represent the top level YAML that Pulumi expects as the Pulumi type.

Lastly, we implement our fn main and create our resources, finishing by printing the YAML to stdout.

use serde_yaml;
use std::collections::HashMap;

mod cloudflare;
mod pulumi;

use cloudflare::Zone;
use pulumi::{Pulumi, Resource};

fn main() -> Result<(), Box<dyn std::error::Error>> {
 let mut pulumi: Pulumi = Pulumi {
 resources: HashMap::new(),
 };

 pulumi.resources.insert(
 "rawkode-dev".into(),
 Resource::Zone {
 properties: Zone {
 zone: "rawkode-dev.com".into(),
 },
 },
 );

 println!("{}", serde_yaml::to_string(&pulumi)?);

 Ok(())
}

What’s Next?

Obviously, this isn’t entirely practical and we can make this 100 times better. So what am I working on next? Well, instead of manually creating all the types that we need for Pulumi to function - what if we could pull in the schema.json that all Pulumi providers have and automatically generate the types? Continuing with Rust’s meta programming, we could achieve this with a procedural macro.

What might that look like?

use pulumi::import_schema;

import_schema!("pulumi/pulumi-cloudflare");

This would generate the types, add functions for requesting outputs, and work with any Pulumi provider.

Stay tuned, I’ll be back with updates as soon as I can.

EKS Blueprints for Pulumi

Isaac Harris — Wed, 20 Apr 2022 18:00:00 +0000

With the launch of Amazon Elastic Kubernetes Service (EKS) in 2017, it is now easier than ever to build, secure, operate and maintain Kubernetes clusters in the cloud. Notably, EKS removed the need to manage and configure underlying compute resources and scaling for clusters. Further, EKS Anywhere brings many benefits to hybrid and on-premises deployments.

These developments have proved to be a huge leap forward in productivity for teams that manage cloud infrastructure, enabling them to focus their efforts on deploying applications to meet the needs of customers and stakeholders.

As companies have matured in their use of Kubernetes, the day 0 through day 2 activities surrounding deployments have started to look similar regardless of where the workload is running. What has emerged is something we call a Shared Services Platform (SSP) – an internal company service that allows application developers to self-service infrastructure environments. SSPs are highly useful for platform teams when they want to share common infrastructure patterns and standardize/automate the provisioning of resources for their development teams. This allows the platform team to be more responsive to development team requests for new environments.

Common activities for teams managing SSPs include:

Setting up and managing multiple environments like DEV, TEST, STAGE, and PROD
Simplifying platform administration with addons
Onboarding Internal Teams via GitOps

Pulumi makes all of these activities easy to automate with built-in secrets management, reusable components, support for end-to-end infrastructure testing, and centralized policy enforcement. We also see new opportunities for simplification in all these activities. We’re excited to be part of the Amazon EKS Blueprints program to help Pulumi users deliver their platforms and applications faster than ever.

With today’s launch, we’re announcing a preview of a few of these scenarios that highlight the power of multi-language components that work across JavaScript/TypeScript, Python, .NET, and Golang in Pulumi. The goal is to get community feedback on these concepts and build more valuable components that meet the production needs of our users.

Here are some examples of how to simplify Kubernetes deployments using EKS Blueprint patterns built as Pulumi multi-language components:

Setting up and managing multiple environments

Pulumi has a concept called Stacks that allows you to deploy the same Pulumi program multiple times, with minor variations to account for environmental differences. Leveraging this with our new Pulumi SSP SDK, you can deploy a cluster to multiple environments with very little code. Here’s an example with one of Pulumi’s supported languages, Python.

from pulumi_ssp import SharedServicesPlatform, ClusterArgsArgs

ssp = SharedServicesPlatform("python-platform", cluster_args=ClusterArgsArgs(kubernetes_version="1.21.0", region="us-east-1"))

That’s it! With a single line of code, you can deploy an EKS cluster in your region of choice and the version of Kubernetes you want. You’ll get the default EKS node group with this configuration, but what if you want more control? Let’s take a look at that with another supported language, TypeScript.

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

const sharedServicesPlatform = new ssp.SharedServicesPlatform("my-platform", {
 clusterArgs: {
 kubernetesVersion: "1.21.0",
 region: "us-east-1",
 },
});

sharedServicesPlatform.addManagedNodeGroup({
 name: "my-managed-group",
 desiredSize: 1,
 minSize: 1,
 kubernetesVersion: "1.21.0",
 maxSize: 2,
 instanceTypes: ["t3.medium"],
});

Our multi-language SDK provides some convenience functions that allow you to add NodeGroups and ManagedNodeGroups with just a few lines of configuration.

Simplifying Platform Administration with Addons

Of course, a Kubernetes cluster with nothing on it isn’t going to give you the platform your organization needs to onboard teams and provide the level of redundancy and resiliency you need. So how can you add common Kubernetes deployments to handle observability, monitoring, and other “day 1 + day 2” tasks? Addons.

Our Pulumi SSP also provides a clusterAddon convenience function that allows you to deploy things with a single line.

A must-have for all Kubernetes clusters is the metrics-server and node-problem-detector, so let’s add these. We’ll stick with TypeScript for this one.

sharedServicesPlatform.clusterAddon({
 name: "metrics-server",
});

sharedServicesPlatform.clusterAddon({
 name: "node-problem-detector",
 version: "0.8.10"
});

Of course, you can easily leverage Pulumi’s integration with a variety of observability tools like Datadog and SumoLogic as well. We will be building more addons over the next few iterations, and we encourage you to reach out on our Community Slack and let us know what you’d like to see.

Onboarding an Internal Team via GitOps

Lastly, Pulumi SSP allows platform teams to onboard teams to the platform, also with a convenience function call.

This time we’ll go wild and show what this looks like with CSharp.

var ssp = new SharedServicesPlatform("csharp", new SharedServicesPlatformArgs
 {
 ClusterArgs = new Pulumi.Ssp.Inputs.ClusterArgsArgs
 {
 KubernetesVersion = "1.21.0",
 Region = "us-east-1",
 }
 });

 ssp.OnboardTeam(new SharedServicesPlatformOnboardTeamArgs
 {
 Name = "payments",
 Controller = "pulumi",
 Repository = "github.com/awesome-org/payments-team/infra"
 });

Onboarding a team to the platform is a wrapper for creating a namespace. Soon, this will add resource quotas and a GitOps delivery pipeline. We’ll initially support ArgoCD and the Pulumi Operator, but support for FluxCD will be added shortly after.

Conclusion

The EKS Blueprints program is helping to simplify the process of managing a shared services platform on Kubernetes by defining standard patterns that every engineering team will find useful. We’d love to get your feedback on this approach and areas where you want to see more high-level components that simplify everyday infrastructure tasks. Check out these code examples and give us your feedback in our EKS Blueprints repo.

Using Go Generics with Pulumi

David Flanagan — Thu, 31 Mar 2022 14:00:00 +0000

This post is outdated. For the latest on Go Generics, visit this blog post.

March 15th, 2022… just two weeks ago. The Go team released Go 1.18 to the world. What seems like a trivial point release actually brings a huge new feature to the Go language: Generics.

In this article, I want to show you how you can use this new feature to build a great developer experience with your abstractions for your Pulumi programs.

Using Go 1.18

The first thing you need to do is ensure you have Go 1.18 installed. You can run go version to check. If you see anything less than 1.18, you’ll need to go upgrade first. The second thing you need to do is update the go.mod in your Pulumi program to specify 1.18 as the minimum version.

go 1.18

Once you’ve done these two steps, you’re ready to start using generics in your Pulumi programs.

Using Generics

Let’s start by asking a question. What is a good use-case for generics? In my experience, generics work really well for allowing us to provide a common interface to our consumers (developers using our APIs) that allows them to use that same interface to accomplish a collection of similar tasks that require different implementations.

For example, let’s assume we want to provide a platform to our developers and allow them to install ANY Kubernetes resource. Our goal is to provide an AddComponent method that they can call to install either pre-supported components, components created by the platform team, or their own custom components. The glue and important aspect here is that all these components conform to the same interface.

Defining The Interface

In the simplest form, we just need an Install function to call that returns either an error or an array of Pulumi resources.

type Component interface {
 Install(ctx *pulumi.Context, name string) ([]pulumi.Resource, error)
}

Creating our Components

Now we need to provide a component that satisfies this interface. So let’s assume that we want to install nginx. First, we create a struct that contains fields for any points of configuration. For today’s example, we’ll just request the version to be installed and a name; the name being used to ensure if the component is installed more than once, it can be uniquely identified.

type Nginx struct {
 Version string
}

func (c *Nginx) Install(ctx *pulumi.Context, name string) ([]pulumi.Resource, error) {
 return []
}

From there, we can begin to flesh out the Install implementation for nginx.

func (c *Nginx) Install(ctx *pulumi.Context) ([]pulumi.Resource, error) {
 deployment, err := appsv1.NewDeployment(ctx, name, &appsv1.DeploymentArgs{
 Metadata: &metav1.ObjectMetaArgs{
 Labels: pulumi.StringMap{
 "app": pulumi.String(name),
 },
 },
 Spec: &appsv1.DeploymentSpecArgs{
 Replicas: pulumi.Int(3),
 Selector: &metav1.LabelSelectorArgs{
 MatchLabels: pulumi.StringMap{
 "app": pulumi.String(name),
 },
 },
 Template: &corev1.PodTemplateSpecArgs{
 Metadata: &metav1.ObjectMetaArgs{
 Labels: pulumi.StringMap{
 "app": pulumi.String(name),
 },
 },
 Spec: &corev1.PodSpecArgs{
 Containers: corev1.ContainerArray{
 &corev1.ContainerArgs{
 Name: pulumi.String("nginx"),
 Image: pulumi.String(fmt.Sprintf("nginx:%s", c.Version)),
 Ports: corev1.ContainerPortArray{
 &corev1.ContainerPortArgs{
 ContainerPort: pulumi.Int(80),
 },
 },
 },
 },
 },
 },
 },
 })
 if err != nil {
 return nil, err
 }

 return []pulumi.Resource{
 deployment,
 }, nil
}

This is rather contrived, but hopefully you can see the power of using generics as an interface for platform engineering. Our AddComponent implementation for nginx could return a deployment, a service, an ingress with horizontal pod auto-scalers, or any other resource that you want.

Using the Components

Finally, we create our generic function, AddComponent, and start having some fun.

func AddComponent[C Component](ctx *pulumi.Context, name string, component C) ([]pulumi.Resource, error) {
 return component.Install(ctx, name)
}

func main() {
 pulumi.Run(func(ctx *pulumi.Context) error {
 AddComponent(ctx, "my-nginx", &Nginx{Version: "1.14.2"})

 return nil
 })
}

Now you and your organization can provide a repository of these components for your developers to consume with their platforms.

The possibilities are endless.

Have fun and see you soon! 👋

Introducing the Pulumiverse

David Flanagan — Wed, 30 Mar 2022 10:00:00 +0000

Today, we’re excited to announce that we’re working with the Pulumi community to provide a place to interact and collaborate on Pulumi-based libraries, projects, and educational materials: the Pulumiverse.

This project is especially important to me, because it’s an idea that I’ve tried in the past, 2018 😯, and failed to commit to and give it the attention it deserves.

Fortunately, two other wonderful Pulumi community members stepped up and started to put together their own programme and with me now being at Pulumi, the timing was amazingly serendipitous.

I spoke with Ringo De Smet and Simen A. W. Olsen, the founding members of the Pulumiverse.

Ringo, Head of CI/CD at Napoleon Games, had this to say about why he’s excited to create the Pulumiverse:

For infrastructure automation, we had other great tools which preceded Pulumi: Chef, Puppet, Ansible. Any of these tools have a vibrant community of people preventing that all of us need to re-invent the wheel. We had Sous-Chefs for Chef & Vox Pupuli for Puppet. But I see a lot of Pulumi users implementing the same stuff over and over again. That’s why I think Pulumi needs it’s own community. So I started it: Pulumiverse

Simon, a Developer at Bjerk AS, shared:

I imagine a community filled with like-minded people who build and support Pulumi providers, opinionated components, configurations and share ideas on how we can utilize the power of Pulumi in new ways. So I created Pulumiverse to share my enthusiasm, give back to Pulumi and support developers by building a platform where we can work together!

What is the Pulumiverse?

Pulumiverse, in the simplest form, is a GitHub organization. It provides a community-operated place for anyone to communicate, contribute, and collaborate with other members of the Pulumi community and build abstractions and SDKs that can be shared and used by anyone.

There are many libraries or collections of components for Pulumi out there. Most of them are made based on requirements of individual companies and developers. Pulumiverse aims to make a community where these libraries can be created and where opinionated configurations for Pulumi resources can be stored and discussed.

Current Projects

The Pulumiverse launches with just a few projects, but we know that, with the support of such an amazing community, the Pulumiverse will grow and grow and provide invaluable resources for anyone who wants to build or use Pulumi for a library or project.

Awesome Pulumi

🐙 Awesome Pulumi

Everybody loves an awesome list, and this one delivers to you a list of awesome Pulumi resources, books, tutorials, talks, and much more.

Want your project listed? Open a PR. We can’t wait to share it with everyone.

Kubernetes SDKs

🐙 Kubernetes SDKs

The Kubernetes SDKs project aims to provide multi-language SDKs for interacting with Kubernetes Custom Resource Definitions (CRDs). Currently, it automatically builds SDKs for:

ArgoCD
CertManager
Contour
Crossplane
Istio
Kong Ingress
Knative
RedPanda
Tyk

This is just the beginning, and we want to expand this collection quickly. So if you’re working with Kubernetes and want a rich developer experience for authoring custom resources, open an issue and let us know what you need.

Pulumi Concourse & Unifi

These are community-maintained providers and are examples of how you can share your providers with the world as part of the Pulumiverse.

Your Project?

Got your own library that you think would be beneficial to the community?

Join us in the #pulumiverse channel on the Pulumi Slack, and we’ll be happy to help you get it over to the Pulumiverse.

We’ll see you soon! 👋

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?

Hierarchical Config: The Interim Solution

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

This blog post discusses hierarchical config before Pulumi ESC was released. ESC makes hierarchical config easy.

A really common question that we receive on the Pulumi team is, “How can we set config at a project level, that can be used across all stacks?”.

When I say “really common” … I mean really, really common.

This issue was first open in 2018 and has received 52 votes from the community. Not only that, we’ve had plenty of similar issues created over the years too.

This is clearly a feature that our community has asked for! We’re happy to say that we delivered the first part of our plans to support hierarchical config in early November 2022. While we believe this new functionality satisfies most customer requests, below are some other approaches you can also use.

Project Level Config

Typically, when you need to access the stack configuration in a Pulumi program, you use the config package.

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

const config = new Config();
const region = config.require("region");

import (
 "github.com/pulumi/pulumi/sdk/v3/go/pulumi/config"
)

conf := config.New(ctx, "")
region := conf.Require("region")

import pulumi

config = pulumi.Config();
region = config.require('region');

using Pulumi;

var config = new Config();
var region = config.Require("region");

This code will reach from the Pulumi.<stack-name>.yaml file and give you access to the configuration values for the prefix you want to load.

So if you want project level config that works across all stacks, you can “hard code” the configuration. It sounds too simple, right?

export const projectLevelConfig = {
 region: "us-west-2",
 encryptionKmsKey: "arn:aws:kms:us-west-2:...",
 issueEmail: "bugs@ellingsonmineral.com"
};

type ProjectLevelConfig struct {
 Region string
 EncryptionKmsKey string
 IssueEmail string
}

const projectLevelConfig = ProjectLevelConfig{
 Region: "us-west-2",
 EncryptionKmsKey: "arn:aws:kms:us-west-2:...",
 IssueEmail: "bugs@ellingsonmineral.com"
}

projectLevelConfig = {
 "region": "us-west-2",
 "encryptionKmsKey": "arn:aws:kms:us-west-2:...",
 "issueEmail": "bugs@ellingsonmineral.com"
}

var projectLevelConfig = new Dictionary<string, string>
{
 { "region", "us-west-2" },
 { "encryptionKmsKey", "arn:aws:kms:us-west-2:..." },
 { "issueEmail", "bugs@ellingsonmineral.com"
}

These objects/structs/dictionaries can all be consumed and imported across the various components and files within your Pulumi program, but they cannot be used at an organizational level across multiple Pulumi programs … unless you’ve got a mono-repo. Do you? 😅

Organization Level Config

So if you want to provide organizational level config, you need to fall deeper into the programming language ecosystem that you’re using to build your infrastructure. Every programming language has a way to parse and consume JSON and YAML files. Better yet, every programming language has a way to fetch a remote JSON/YAML file and give you a object/struct/dictionary.

So really, there’s no reason you can’t use a remote JSON file to provide a common configuration object across all your Pulumi programs. That being said, there are definitely reasons you shouldn’t use a remote JSON file. Maintaining a remote JSON file is much more of a burden than it will initially seem. As you add more values to your JSON file and more teams/projects begin to rely on it, you’ll start to feel the pain of schema management. How do I know that the JSON I’m pulling down has the values I need and that fields haven’t been changed or replaced? 😬

So while I 💯 feel like you shouldn’t do this, you can if you really need to. Just make sure you understand the tradeoffs and enforce a schema.

A common way to manage schema is to use a JSON Schema or CUE to define the structure of your JSON file.

By using one of these methods, you can publish a schema that is available within your organization and people can have confidence that the value they pull remotely can be deserialized to a strict type. Using CI/CD you can also ensure the value itself conforms to the schema before updating the public document.

With JSON Schema, you’d define something like:

{
 "type": "object",
 "properties": {
 "region": {
 "type": "string",
 "default": "us-west-2"
 },
 "encryptionKmsKey": {
 "type": "string",
 "default": "arn:aws:kms:us-west-2:..."
 },
 "issueEmail": {
 "type": "string",
 "default": "bugs@ellingsonmineral.com"
 }
 }
}

With CUE, this is much more concise. CUE is really awesome and I encourage you to check it out.

region: string | *"eu-west-2"
encryptionKmsKey: string | *"arn:aws:kms:eu-west-2:..."
issueEmail: string | *"bugs@ellingsonmineral.com"

Pulumi Native Hierarchical Configuration

So we’ve worked out that project level configuration is a data structure within our Pulumi programs and it works pretty darn well.

However, the organization level config is prone and rife with pain, confusion, and delusion. It requires non-trivial tooling and process to ensure that a global document is valid and consistent with downstream consumers. What I’ve shown you is a “if you must” approach that I would use myself. We’ve also not even handled the “merge” of organization level with project level overrides, and then stack level overrides. Of course, with code it’s all possible, but it’s more and more code that you need to write that we don’t want you to need to write, right? Right!

Pulumi wants to make this better for you, which is why we added project-level config support and why we are actively exploring additional enhancements. If you want to follow along with our progress on improving the configuration experience, I suggest you watch/subscribe to this issue.

If you want to share your opinions on how YOU would like this feature to be implemented, jump into the comments. We’d love to hear from you!

Speak soon.

Easier IaC adoption with improved `pulumi import` experience

Fraser Waters — Tue, 15 Mar 2022 00:00:00 +0000

Last year, we introduced a new Pulumi feature that allows you to import existing infrastructure into your Pulumi program. Not only did it bring the resource into the Pulumi state file, but it could generate the source code for your Pulumi program too. Today, we’re excited to announce that we’ve listened to feedback and delivered a plethora of updates and fixes to streamline the import experience; to make it more useful, more convenient, and more powerful.

At Pulumi, we understand that many cloud engineers and platform teams around the world don’t have the luxury of greenfield projects, more often than not we’re stuck with the impossible task of “refactoring” or “migrating” existing projects to more modern stacks to help increase team productivity, velocity, and stability. These projects aren’t trivial and we want to make it easier for teams and organizations to bring their infrastructure into a cloud engineering world. Oh, and worry not you lucky greenfielders … even if you just wanna ClickOps your way through some resources and import them into your program; that’s gonna work just fine too; we won’t tell if you don’t 😉.

To help you understand the changes we’ve made to help you on your journey, let’s take a look at some side-by-side examples of how pulumi import used to work vs. what we’re releasing today in Pulumi 3.26.

Example: AWS S3 Bucket

Previously when importing an S3 bucket, we would set the default values for properties like acl and forceDestroy. The new behavior will not include properties with default values in the generated code, keeping your code inline with how you’d write it yourself. Artisanal codegen for the artisanal cloud engineer.

Code Comparison

This code would have been generated by the older implementation:

const my_bucket = new aws.s3.Bucket("my-bucket", {
 acl: "private",
 bucket: "my-bucket-3f85c54",
 forceDestroy: false,
}, {
 protect: true,
});

This code will be generated by the newer implementation:

const my_bucket = new aws.s3.Bucket("my-bucket", {
 arn: "arn:aws:s3:::my-bucket-3f85c54",
 bucket: "my-bucket-3f85c54",
 hostedZoneId: "Z3BJ6K6RIION7M",
 requestPayer: "BucketOwner",
}, {
 protect: true,
});

The above accurately reflects what the providers Read function has told us of the inputs set for this bucket, although due to the way the AWS provider works, we could elide all these properties. This is because the provider will use outputs saved in the state file and the new inputs to calculate the update diff. A property that exists in the old output and is missing from the new inputs is simply left at the old output value. As none of the properties for Bucket are marked required the following works as well and is equivalent:

const my_bucket = new aws.s3.Bucket("my-bucket", { protect: true });

Example: AWS EC2 Instances

Previously, when trying to import an EC2 instance with pulumi import, you’d be presented with a list of required properties that weren’t satisfied. Like above, the new behavior will read from the provider and inherit the missing properties, providing everything required to correctly import. This provides a cleaner and more intuitive experience for the user.

Old Behavior

$ pulumi import aws:ec2/instance:Instance test i-085d780737c600c7e
aws:ec2:Instance (test):
 error: aws:ec2/instance:Instance resource 'test' has a problem: Missing required argument: "instance_type": one of `instance_type,launch_template` must be specified. Examine values at 'Instance.InstanceType'.
 error: aws:ec2/instance:Instance resource 'test' has a problem: Missing required argument: "launch_template": one of `ami,instance_type,launch_template` must be specified. Examine values at 'Instance.LaunchTemplate'.
 error: aws:ec2/instance:Instance resource 'test' has a problem: Missing required argument: "ami": one of `ami,launch_template` must be specified. Examine values at 'Instance.Ami'.

New Behavior

The import will be successful and we’ll be presented with a rich resource in your language of choice.

const test = new aws.ec2.Instance("test", {
 ami: "ami-082b5a644766e0e6f",
 associatePublicIpAddress: true,
 availabilityZone: "us-west-2c",
 capacityReservationSpecification: {
 capacityReservationPreference: "open",
 },
 cpuCoreCount: 1,
 cpuThreadsPerCore: 1,
 creditSpecification: {
 cpuCredits: "standard",
 },
 iamInstanceProfile: "",
 instanceInitiatedShutdownBehavior: "stop",
 instanceType: "t2.micro",
 metadataOptions: {
 httpEndpoint: "enabled",
 httpPutResponseHopLimit: 1,
 httpTokens: "optional",
 },
 privateIp: "172.31.0.188",
 rootBlockDevice: {
 iops: 100,
 volumeSize: 8,
 volumeType: "gp2",
 },
 securityGroups: ["default"],
 subnetId: "subnet-43f43a1e",
 tenancy: "default",
 vpcSecurityGroupIds: ["sg-4d436f12"],
}, {
 protect: true,
});

test = aws.ec2.Instance("test",
 ami="ami-082b5a644766e0e6f",
 associate_public_ip_address=True,
 availability_zone="us-west-2c",
 capacity_reservation_specification=aws.ec2.InstanceCapacityReservationSpecificationArgs(
 capacity_reservation_preference="open",
 ),
 cpu_core_count=1,
 cpu_threads_per_core=1,
 credit_specification=aws.ec2.InstanceCreditSpecificationArgs(
 cpu_credits="standard",
 ),
 iam_instance_profile="",
 instance_initiated_shutdown_behavior="stop",
 instance_type="t2.micro",
 metadata_options=aws.ec2.InstanceMetadataOptionsArgs(
 http_endpoint="enabled",
 http_put_response_hop_limit=1,
 http_tokens="optional",
 ),
 private_ip="172.31.0.188",
 root_block_device=aws.ec2.InstanceRootBlockDeviceArgs(
 iops=100,
 volume_size=8,
 volume_type="gp2",
 ),
 security_groups=["default"],
 subnet_id="subnet-43f43a1e",
 tenancy="default",
 vpc_security_group_ids=["sg-4d436f12"],
 opts=pulumi.ResourceOptions(protect=True))

 _, err := ec2.NewInstance(ctx, "test", &ec2.InstanceArgs{
 Ami: pulumi.String("ami-082b5a644766e0e6f"),
 AssociatePublicIpAddress: pulumi.Bool(true),
 AvailabilityZone: pulumi.String("us-west-2c"),
 CapacityReservationSpecification: &ec2.InstanceCapacityReservationSpecificationArgs{
 CapacityReservationPreference: pulumi.String("open"),
 },
 CpuCoreCount: pulumi.Int(1),
 CpuThreadsPerCore: pulumi.Int(1),
 CreditSpecification: &ec2.InstanceCreditSpecificationArgs{
 CpuCredits: pulumi.String("standard"),
 },
 IamInstanceProfile: pulumi.Any(""),
 InstanceInitiatedShutdownBehavior: pulumi.String("stop"),
 InstanceType: pulumi.String("t2.micro"),
 MetadataOptions: &ec2.InstanceMetadataOptionsArgs{
 HttpEndpoint: pulumi.String("enabled"),
 HttpPutResponseHopLimit: pulumi.Int(1),
 HttpTokens: pulumi.String("optional"),
 },
 PrivateIp: pulumi.String("172.31.0.188"),
 RootBlockDevice: &ec2.InstanceRootBlockDeviceArgs{
 Iops: pulumi.Int(100),
 VolumeSize: pulumi.Int(8),
 VolumeType: pulumi.String("gp2"),
 },
 SecurityGroups: pulumi.StringArray{
 pulumi.String("default"),
 },
 SubnetId: pulumi.String("subnet-43f43a1e"),
 Tenancy: pulumi.String("default"),
 VpcSecurityGroupIds: pulumi.StringArray{
 pulumi.String("sg-4d436f12"),
 },
}, pulumi.Protect(true))

var test = new Aws.Ec2.Instance("test", new Aws.Ec2.InstanceArgs
 {
 Ami = "ami-082b5a644766e0e6f",
 AssociatePublicIpAddress = true,
 AvailabilityZone = "us-west-2c",
 CapacityReservationSpecification = new Aws.Ec2.Inputs.InstanceCapacityReservationSpecificationArgs
 {
 CapacityReservationPreference = "open",
 },
 CpuCoreCount = 1,
 CpuThreadsPerCore = 1,
 CreditSpecification = new Aws.Ec2.Inputs.InstanceCreditSpecificationArgs
 {
 CpuCredits = "standard",
 },
 IamInstanceProfile = "",
 InstanceInitiatedShutdownBehavior = "stop",
 InstanceType = "t2.micro",
 MetadataOptions = new Aws.Ec2.Inputs.InstanceMetadataOptionsArgs
 {
 HttpEndpoint = "enabled",
 HttpPutResponseHopLimit = 1,
 HttpTokens = "optional",
 },
 PrivateIp = "172.31.0.188",
 RootBlockDevice = new Aws.Ec2.Inputs.InstanceRootBlockDeviceArgs
 {
 Iops = 100,
 VolumeSize = 8,
 VolumeType = "gp2",
 },
 SecurityGroups =
 {
 "default",
 },
 SubnetId = "subnet-43f43a1e",
 Tenancy = "default",
 VpcSecurityGroupIds =
 {
 "sg-4d436f12",
 },
 }, new CustomResourceOptions
 {
 Protect = true,
 });
 ```

Again this reflects what Read has told us of the inputs set for this instance, and again due to the way the AWS provider works many of these inputs could be elided and the provider would pick up the values from the saved output set. The following is again equivalent to the above given the saved state:

const test = new aws.ec2.Instance("test", {
 ami: "ami-082b5a644766e0e6f",
 instanceType: "t2.micro"
}, {
 protect: true,
});

Everything is Better, Yes?

To quote our old friend, Harlan, “Everything is better, yes?”

While we’ve only shown you a couple of examples of this new behaviour, rest assured that the benefits of it stretch far and wide across the majority of Pulumi resources.

If you’ve ever had a problem importing a resource before, we encourage you to try it again and let us know if you run into any problems.

Curious how this all works? Let’s dive in.

Technical details

We’ve never really explained how the import system works before, which has lead to a lot of confusion from users when they encountered errors with it. Given the changes we’re making here we felt it a good time to give a more detailed write up of how the engine works to try and help users understand why their import results are the way they are.

This section requires some understanding of the Pulumi architecture, but that understanding is not necessary to be able to use pulumi import.

The importance of `Provider.Read`

Our import system depends on the ability for a resource provider to be able to read the existing state of a resource and report back to Pulumi the current value of it’s inputs and outputs.

This isn’t always possible to return accurately. For example if a resource’s inputs don’t match up 1-to-1 with it’s output state and the underlying provider can only read the current output state there’s no way for it to always construct the correct input state. There could also be bugs in the provider’s Read method that result in inaccurate reads. We’ve designed the import system to be tolerant to these cases, but it does mean we don’t expect perfect import results for every resource.

The current import system

To import resources with the currently the engine issues the following steps:

Use the providers Read function to get the inputs and outputs for the resource.
Remove all properties from the inputs except for those flagged as required.
Pass that reduced input property set to the providers Check method.
If there are any check failures return an error and fail the import.
Take the result of Check which will have filled in default properties and diff it with the original input set returned from Read.
If there are any diffs copy in the values from the original Read to the resulting input set.
Save the updated input set and the original output set into the stacks state.
Pass the resulting input set to the code generator to generate a new Resource call to match the imported state.

There are a number of problems with the above. The biggest is trying to strip the input set down to only properties that are marked as required. The required flag is a fairly blunt tool that can’t capture that some fields are only required sometimes based on the value of other fields. As such this stripping to just required properties causes many of the following calls to Check to raise check failures.

The next major issue is that we hard fail if check returns failures. There is always the risk of this happening due to limitations of Read, and it doesn’t help the user just throwing an error.

Finally in the cases where the above two issues weren’t hit this data flow had the odd result of setting optional fields to their default values. This isn’t needed and these fields would be better left as blank.

The new import system aims to improve the described issues.

The new import system

The engine will now issue the following steps to import resources:

Use the providers Read function to get the inputs and outputs for the resource.
Pass the input set to the providers Check method.
Warn if there are any check failures.
Save the input and output set from Read into the stacks state.
Pass the input set to the code generator to generate a new Resource call to match the imported state.

Note that we no longer end up with filled in default values in our final result, and we carry on in the face of check failures and so can still generate some code. If providers can give complete and accurate results from Read the above flow will result in correctly generated code. However it doesn’t result in quite the correct stack state, this is due to how the data flow of our import system currently works. Currently we generate code based on the value of inputs in the state file, however normally the value stored at inputs in the state file is the result from Check, not what is directly in the users program. As such when you run the first pulumi up after an import your state file will change slightly as the engine calls Check and saves the inputs with defaults filled in. This should normally be transparent to the user, but there may be some cases where providers think this is a trivial diff.

There are two complications with fixing the above. The first is that during import if Read doesn’t return valid results then Check can fail and so we won’t have a property set returned from it that we can save to the state file. This case will always have to fall back to just storing the properties returned by Read and triggering a check failure during up that will need to be manually resolved. The second complication is that the code generation for import works off the state file rather than a separate data flow specifically for imported resources. We plan on improving this but in the spirit of agility we felt that a slightly better import feature today would be more useful to our users than a perfect import feature later.

Terraform `Read`

Many of Pulumi’s resource providers make use of Terraform providers. We call these bridged providers and all of them use our “terraform-bridge” library to translate between the Terraform API and Pulumi API.

Terraform currently has a slightly odd behavior that missing values for some properties are zero initialized by its Refresh method (what we use to implement Pulumi’s Read method in the terraform bridge). This has the result that when Pulumi asks to read a given Terraform resource some top level properties (such as S3 buckets acl property) come back as missing, while other top level properties and all nested properties (such as S3 buckets versioning.mfaDelete) come back with some zero value.

For example reading an AWS S3 bucket object with the current Terraform bridge results in the following property set:

{
"__defaults": [],
"accelerationStatus": "",
"arn": "arn:aws:s3:::my-bucket-3f85c54",
"bucket": "my-bucket-3f85c54",
"corsRules": [],
"grants": [],
"hostedZoneId": "Z3BJ6K6RIION7M",
"lifecycleRules": [],
"loggings": [],
"objectLockConfiguration": null,
"replicationConfiguration": null,
"requestPayer": "BucketOwner",
"serverSideEncryptionConfiguration": null,
"tags": {
"__defaults": []
},
"versioning": {
"__defaults": [],
"enabled": false,
"mfaDelete": false
},
"website": null
}

We’ve made a change to the Terraform bridge to try and elide these zero properties that should just be missing. Reading the same S3 bucket with these changes gives the following much smaller property set:

{
"__defaults": [],
"arn": "arn:aws:s3:::my-bucket-3f85c54",
"bucket": "my-bucket-3f85c54",
"hostedZoneId": "Z3BJ6K6RIION7M",
"requestPayer": "BucketOwner",
"website": null
}

We’ll continue to work on the Terraform bridge to give better results here. For example the website property on the bucket should probably be missing rather than null.

Feedback

We’re aware this could have a large impact to some of our users so we wanted to make sure we explained these changes well. If you have questions or concerns about this change let us know in our community Slack or in GitHub Discussions.

Executing Remote Commands with Pulumi

David Flanagan — Thu, 03 Feb 2022 22:10:00 +0000

We recently announced in our release blog (66) a new package: Command. In this article, I want to show you a practical application of this that will allow us to deploy k3s to a DigitalOcean Kubernetes droplet. We’ll then leverage the Command package to run a remote command to fetch the kubeconfig, generated on the VM, and pull it down to create a Kubernetes provider to deploy nginx.

So, let’s get started by deploying our DigitalOcean droplet.

The first thing we’re going to do is generate an SSH key for the machine.

const sshKey = new tls.PrivateKey("sshKey", {
 algorithm: "RSA",
 rsaBits: 4096,
});

// Optional export of the key in-case you want to store it on disk.
export const privateKey = sshKey.privateKeyPem;

// Register the SSH key with DigitalOcean
const doSshkey = new digitalocean.SshKey("sshKey", {
 publicKey: sshKey.publicKeyOpenssh,
});

Then we’ll want to create a cloud-init configuration to pass to the droplet as user-data.

const cloudConfig = cloudinit.getConfig({
 gzip: false,
 base64Encode: false,
 parts: [
 {
 contentType: "text/x-shellscript",
 content: fs.readFileSync("../cloud-init/ensure-curl.sh", "utf8"),
 },
 {
 contentType: "text/x-shellscript",
 content: fs.readFileSync("../cloud-init/install-k3s.sh", "utf8"),
 },
 ],
});

There’s nothing terribly fancy about these scripts, but we’ll share them anyway 😃

This first one makes sure that curl is available on the machine.

#!/usr/bin/env sh
# ../cloud-init/ensure-curl.sh
DEBIAN_FRONTEND=noninteractive apt update && apt install --yes curl

This script will fetch the public IPv4 address from the DigitalOcean metadata service and pass that IP address through to k3s installer as the listen/bind address. This ensures that our Kubernetes provider in the Pulumi program can speak with the API server.

#!/usr/bin/env sh
# ../cloud-init/install-k3s.sh
PUBLIC_IP=$(curl -w "\n" http://169.254.169.254/metadata/v1/interfaces/public/0/ipv4/address)
curl -sfL https://get.k3s.io | sh -s - --bind-address ${PUBLIC_IP}

Now that we have some user-data, we can create a droplet and pass it through.

const k3sVm = new digitalocean.Droplet(
 "k3s",
 {
 name: "k3s",
 image: "ubuntu-20-04-x64",
 region: "lon1",
 size: "s-1vcpu-1gb",
 sshKeys: [civoSshKey.id],
 userData: cloudConfig.then((c) => c.rendered),
 },
 {
 replaceOnChanges: ["diskImage", "script"],
 }
);

Now, for the fun bit. Previously, there’d be no way to get the kubeconfig from the VM. Meaning that we’d need to use static manifests to deploy our workloads to k3s. This would usually be done by adding more and more scripts to the user-data and rendering them with cloud-init. This approach is not bad, but we lose the rich interface that Pulumi provides for authoring our Kubernetes resources. With the Command package, we can now execute a command on our VM and pull down that kubeconfig to be used to create our provider.

const fetchKubeconfig = new command.remote.Command("fetch-kubeconfig", {
 connection: {
 host: k3sVm.ipv4Address,
 user: "root",
 privateKey: sshKey.privateKeyPem,
 },
 create:
 // First, we use `until` to monitor for the k3s.yaml (our kubeconfig) being created.
 // Then we sleep 10, just in-case the k3s server needs a moment to become healthy. Sorry?
 "until [ -f /etc/rancher/k3s/k3s.yaml ]; do sleep 5; done; cat /etc/rancher/k3s/k3s.yaml; sleep 10;",
});

The Command package makes the stdout of the command we run available in our program, so creating the Kubernetes provider is as simple as:

const kubernetesProvider = new kubernetes.Provider("k3s", {
 kubeconfig: fetchKubeconfig.stdout,
});

Now, for the final step - deploying nginx.

const nginx = new kubernetes.apps.v1.Deployment(
 "nginx",
 {
 spec: {
 selector: {
 matchLabels: {
 app: "nginx",
 },
 },
 template: {
 metadata: {
 labels: {
 app: "nginx",
 },
 },
 spec: {
 containers: [
 {
 name: "nginx",
 image: "nginx",
 },
 ],
 },
 },
 },
 },
 {
 provider: kubernetesProvider,
 }
);

Simple.

The Command package works for local and remote commands and the possibilities are endless.

Happy hacking!

Kubernetes SDKs from the Pulumiverse

David Flanagan — Wed, 29 Dec 2021 13:32:16 +0000

Pulumi provides an amazingly rich interface for developers and operators to define their Kubernetes workloads, providing typed access to recourses from the Kubernetes API and allowing our IDEs to provide code completion and refactoring opportunities through the native language plugins.

As great as that is, it’s always gotten a little cumbersome when it comes to Custom Resource Definitions (CRDs), as the first option is to leverage the CustomResource escape-hatch that allows you to define any Kubernetes object you wish; however this does mean we lose the rich interface we’ve become accustomed to.

new k8s.apiextensions.CustomResource('marvin-the-martian', {
 apiVersion: 'looneytunes.com/v1990',
 kind: 'LooneyTune',
 metadata: {
 name: 'Marvin the Martian',
 planet: 'mars'
 },
 spec: {
 armor: {
 style: 'hoplite',
 colors: ['green', 'red'],
 },
 phrases: [
 'Wheres the kaboom',
 'Oh, drat these computers. They’re so naughty and so complex. I could pinch them',
 'I do so enjoy observing the flora and fauna of that tiny planet',
 'Please, sir. Do not interrupt my chain of thought. I am a busy Martian',
 'Brace yourself for immediate disintegration'
 ]
 },
});

While this is a huge unblocker for working with Kubernetes, we can do better.

crd2pulumi

Back in August, 2020, we published crd2pulumi. crd2pulumi allows you to generate a Pulumi SDK for any Kubernetes Custom Resource. Now, when you want to start using cert-manager, Ambassador, Linkerd, or any other project within the Kubernetes and Cloud Native space; you can download the CRD YAML and run crd2pulumi, which will generate the SDK for whatever supported language you wish. Neat?

I’ve been using this approach for the past year and it’s the easiest way to provide that rich interface to developers, but the repetition can become a little frustrating. For every new project that I was working on, I’d need to build out the same automation and there’s also the maintenance burden of ensuring the SDK is up to date with the latest version deployed to the cluster.

Further more, these SDKs never change; if you generate a SDK for cert-manager and someone else does, supporting the same version - there’s no difference in the code that is generated. Do we really need everyone to do this themselves?

Perhaps some further tooling is required.

Kubernetes SDKs at Pulumiverse

I like solving problems like this. It’s not technically challenging, the hard work is already done by the team supporting crd2pulumi. The problem we need to solve here is a quality of life / developer experience issue. How can we make this easier for developers to consume?

For us to make this easier, we have two issues:

How do we automate the generation of the SDKs, ensuring that the SDKs are always up to date?
Where do we publish them?

Automation

GitHub Actions plays such a large role in our developer world these days, especially for open source projects. So it was an easy choice to make that any automation I build out for this will be built on top of GitHub Actions. Knowing that we want the SDKs to be up to date, we also know that this automation must run on a regular cadence. As such, the beginning of our GitHub Action can take some shape:

name: Build SDKs

on:
 schedule:
 - cron: "10 3,15 * * *"

Here, we have our GitHub Action scheduled to run every day at 3:10am and 3:10pm.

Next, we need to know what to build. We don’t want to build EVERY SDK that the project is aware of, so we need some code to look up GitHub Releases for some new tags. For this, we can drop to Python to do some quick lookups.

from atoma import parse_atom_bytes
from datetime import datetime, timedelta, timezone
from json import dumps
from requests import get as httpget
from typing import List, Mapping, Optional
from yaml import safe_load, YAMLError
import sys


def has_been_updated(updated_at: Optional[datetime] = None) -> bool:
 if updated_at == None:
 return False
 hours_since: int = int(sys.argv[1]) if len(sys.argv) > 1 else 12

 return (datetime.now(timezone.utc) - updated_at) < timedelta(hours=hours_since)


def get_new_tags(repository: str) -> List[str]:
 response = httpget(f'https://{repository}/tags.atom')
 feed = parse_atom_bytes(response.content)

 return list(map(lambda entry: entry.title.value, filter(lambda entry: has_been_updated(entry.updated), feed.entries)))


with open("./sdks.yaml", "r") as stream:
 try:
 sdks: Mapping[str, str] = safe_load(stream)
 except YAMLError as exc:
 print(f"Error parsing SDK Yaml: {exc}")

sdks_to_build: List[str] = []
for name, repository in sdks.items():
 for tag in get_new_tags(repository):
 sdks_to_build.append(
 f'{name}|{repository}|{tag}')

print(dumps(sdks_to_build))

This Python will loop through our configured SDKs, loaded from a YAML document, and reach out to the atom feed that GitHub provides for every public repository. This allows us to quickly loop over the tags/releases and find any published within the last window. We don’t need to do anything else besides print this to the terminal and allow GitHub Actions to store the output for use in our build matrix.

jobs:
 find_new_tags:
 runs-on: ubuntu-latest
 steps:
 - ... random boring steps

 - id: find_new_tags
 run: echo "::set-output name=sdk_versions::$(poetry run python ./bin/find-new-tags.py ${{ github.event.inputs.since_hours }})"

 outputs:
 sdk_versions: ${{ steps.find_new_tags.outputs.sdk_versions }}

build_nodejs_sdk:
 needs: find_new_tags
 runs-on: ubuntu-latest
 strategy:
 matrix:
 version: ${{ fromJson(needs.find_new_tags.outputs.sdk_versions) }}

Once our Python script has run and the output stored, we’re using a helper function from GitHub called fromJson to use the output as a dynamic input to their matrix build system. We’ll get exactly one job for every new tag that we’ve found.

The job to generate the SDK and publish it to npm looks like this:

- name: crd2pulumi-generate-sdk
 run: |
 IFS='|' read -r -a build_parts <<< "${{ matrix.version }}"
 mkdir -p ./_output
 curl -fsSL -o crd.yaml https://doc.crds.dev/raw/${build_parts[1]}@${build_parts[2]}
 crd2pulumi --nodejsName ${build_parts[0]} --nodejsPath ./_output ./crd.yaml --force
 # Fix Package Name
 sed -ie "s#@pulumi/${build_parts[0]}#@pulumiverse/${build_parts[0]}#g" ./_output/package.json
 # Fix Package Version
 sed -ie "s#\"version\": \"\"#\"version\": \"${build_parts[2]}\"#g" ./_output/package.json
- run: npm publish --access=public
 working-directory: ./_output
 env:
 NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Like I said earlier, the hard work was already done; we just needed to glue some automation together to improve the DX.

Publishing

Now that we have this system in place to regularly check and build new SDKs, we needed a home for them to live. Recently, some amazing Pulumi community members, worked together on a new GitHub initiative, with Pulumi support, called Pulumiverse. Pulumiverse aims to be a community lead and governed initiative to provide new abstractions and libraries for consumers of Pulumi to use and make their lives easier. This is the perfect place for these SDKs to live.

You can checkout the repository today.

SDKs

Currently, the automation publishes NodeJS SDKs (JavaScript and TypeScript) to npm, but plans to add Python will be executed very soon. We’re also looking to publish packages for dotNet, but research is still underway.

I don’t expect to publish packages for Go … sadly, because Go modules use GitHub for fetching source code - we’d need to publish generated code to the repository and I’m not entirely keen on that approach. I could possibly be persuaded, but I’d love some suggestions for alternate ways to resolve this.

We currently provide SDKs for:

argocd
cert-manager
crossplane
knative
redpanda

Need more? No problem! Open a pull request adding a SINGLE LINE to sdks.yaml and the SDK will be available shortly.

Nice.

Prior Art

While writing this article, I discovered an old repository within the Pulumi organization that actually did something similar to this last year 😮 It’s not automated like this new initiative, but it was great to find that previous attempts to improve the developer experience for Kubernetes teams using Pulumi. Mad props to Paul Stack and Albert Zhong.

So that’s it! Thanks for reading. We hope you find this useful and we encourage you to join us and help by adding your favourite Kubernetes SDKs to the automation.

We’ll see you in 2022, have a great New Year. 🎉

Improving the GitOps Pipeline with the Pulumi Operator

David Flanagan — Fri, 24 Dec 2021 17:08:06 +0000

Check out version 2.0 of the Pulumi Kubernetes Operator.

This time last year, I presented Applying the Law of Demeter to GitOps at GitOps Days 2020. The Law of Demeter is a design principle, proposed in 1988, which encourages loose coupling between systems. During this session, I wanted the audience to understand and be able to identify when their applications and continuous delivery pipelines have too much knowledge of the platform in which they’re going to run. As an industry, we’re seeing a great deal of momentum towards Platform Engineering and with this comes a Broca divide, a strict division of responsibilities: to build a platform and to consume a platform.

Instead, the platform will provide everything the application needs to function. We’ve seen a lot of this before, notably via the 12-factor manifesto.

Over the course of the last year I’ve collected my thinking more and more around this pattern, and I condensed it down into a single tweet:

#GitOps isn’t a decision of push vs pull for continuous delivery. It’s more deciding whether your application tells the environment how to deploy itself, or whether the environment tells your application how to run.

You want the latter. You want GitOps.

So what does this all mean in a more practical sense?

Ingress Example

Time and time again I see the same violation of the Law of Demeter with Kubernetes and GitOps: Ingress.

Application delivery teams require Ingress resources within Kubernetes to expose their applications to their customers. Often, Helm or Kustomize is used to provide bases that can be extended for each environment. We can see an example of the boundary violation in the Kustomize examples. I’m not calling out Kustomize here; Pulumi also has examples of this pattern.

Unfortunately, this pattern has become quite common. Leaking environment information down the stack is what we’re trying to avoid, but doing so can be rather tricky.

To understand this challenge in concrete terms, let’s look at an example of a simple Ingress resource:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: minimal-ingress
 annotations:
 nginx.ingress.kubernetes.io/rewrite-target: /
spec:
 rules:
 - host: staging.example.org
 http:
 paths:
 - path: /testpath
 pathType: Prefix
 backend:
 service:
 name: test
 port:
 number: 80

The violation here is host: staging.example.org inside of the application team resources. We now have a constraint binding the platform and the application together. If we continue down this path, the platform team can’t launch new environments without first reaching out to the application teams to ensure they have a base that can provide the correct domain name for these resources.

What we really want is for the platform team to be able to launch platforms whenever they want, increasing their ability to iterate and experiment with the platform. At the same time, by removing the bases and variance from the application teams, we ensure that they have a single blueprint for how to deploy their application. Win/Win.

Sadly, this is a difficult problem to solve; though not impossible.

Pulumi Operator

The Pulumi Operator hit major milestone in October this year, releasing version 1.0.

The Pulumi Operator allows us to leverage the power of Pulumi at the application team level for GitOps. This bond between Pulumi for building platforms and Pulumi for consuming platforms means we can have a strictly typed exchange of “knowns” between our platform and our application that happens at execution time.

Let’s imagine, in TypeScript, that we have the following versioned interface:

export interface Environment {
 name: string;
 baseDomain: string;
 serviceNamespace: string;
 ingressEnabled: boolean;
 networkPoliciesEnforced: boolean;
}

With this contract, the Platform Engineering team can ensure that every cluster, or namespace, has a ConfigMap called environment can be consumed by the Pulumi Operator. In this, the Pulumi program, the GitOps delivery pipeline from the application team, can begin to grok the environment to which it is being deployed. With this knowledge, it can begin to augment the manifests before they’re applied to the cluster.

Let’s go back to our Ingress example and see how this could be done.

First, let’s assume our Platform team have deployed a ConfigMap like such:

apiVersion: v1
kind: ConfigMap
metadata:
 name: environment
data:
 v1: |
 {
 "name": "production",
 "baseDomain": "pulumi.com",
 "serviceNamespace": "utils",
 "ingressEnabled": true,
 "networkPoliciesEnforced": true
 }

The specification for what an environment looks like will differ from organization to organization, but this hopefully provides enough context for some of the things you may wish to encapsulate this way.

Next, our application team defines their delivery via Pulumi, too. The first thing they do as part of the delivery is load the environment config. This data can then be used to augment any resources that need to be environment aware.

import * as k8s from "@pulumi/kubernetes";

const cm = k8s.core.v1.ConfigMap.get("environment", "environment", {});

export interface Environment {
 name: string;
 baseDomain: string;
 serviceNamespace: string;
 ingressEnabled: boolean;
 networkPoliciesEnforced: boolean;
}

const env = cm.data.apply((data): Environment => JSON.parse(data["v1"]));

const ingress = new k8s.networking.v1.Ingress(name,
 {
 metadata: {
 labels: labels,
 },
 spec: {
 rules: [
 {
 host: pulumi.interpolate`mysvc.${env.baseDomain}`,
 http: {
 paths: [
 {
 path: "/",
 backend: {
 serviceName: serviceName,
 servicePort: "http",
 }
 },
 ],
 },
 }
 ]
 }
 }
);

That’s it! We’ve got isolated delivery pipelines for both the platform team and the application team, leveraging GitOps and continuous reconciliation, without leaking any information across the stacks.

Pulumi is already seeing considerable adoption and success with platform teams, and I’m excited to see further adoption of the Pulumi Operator and application teams harnessing the power of GitOps with Pulumi.

Pulumi Blog: David Flanagan

Deploying Amazon EKS Anywhere on Bare Metal

How it works (the short version)

Setting up your bare metal servers

Give it a try!

Deploying a URL Shortener with Cloudflare Workers

Setting Up

Our URL Shortener

Deploying Our Worker

Where’s the Types?!

Hooking Up a Domain

Create a Zone(s)

Fetch a Zone

Creating the Routes

Fin

Complete Code

Patterns for Drift Detection with Pulumi

Why is Drift Detection Important?

Refreshing the World

Workflow Approach

Operator Approach

Making Refresh Your Default

Protect

Ignore Changes

Delete Before Replace

Want to See More?

Extending Pulumi's Language Support via YAML

CUE

JSONNET

Rust

What’s Next?

EKS Blueprints for Pulumi

Setting up and managing multiple environments

Simplifying Platform Administration with Addons

Onboarding an Internal Team via GitOps

Conclusion

Using Go Generics with Pulumi

Using Go 1.18

Using Generics

Defining The Interface

Creating our Components

Using the Components

Introducing the Pulumiverse

What is the Pulumiverse?

Current Projects

Awesome Pulumi

Kubernetes SDKs

Pulumi Concourse & Unifi

Your Project?

Managing my DNS with Pulumi

Overview

Fetching the Controller

Creating Records

Configuring Apex

Configuring for Email

Where is my DNS?

How Does it Work?

What’s Next?

Hierarchical Config: The Interim Solution

Project Level Config

Organization Level Config

Pulumi Native Hierarchical Configuration

Easier IaC adoption with improved `pulumi import` experience

Example: AWS S3 Bucket

Code Comparison

Example: AWS EC2 Instances

Old Behavior

New Behavior

Everything is Better, Yes?

Technical details

The importance of Provider.Read

The current import system

The new import system

Terraform Read

Feedback

Executing Remote Commands with Pulumi

Kubernetes SDKs from the Pulumiverse

crd2pulumi

Kubernetes SDKs at Pulumiverse

Automation

The importance of `Provider.Read`

Terraform `Read`