0% found this document useful (0 votes)

230 views51 pages

Pulumi Sample

Uploaded by

Sanju Naik

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

230 views51 pages

Pulumi Sample

Uploaded by

Sanju Naik

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 51

The Pulumi Book

A developer’s guide to programming the cloud with TypeScript

and Amazon Web Services

Christian Nunciato

This book is for sale at http://leanpub.com/pulumi

This version was published on 2021-11-14

This is a Leanpub book. Leanpub empowers authors and publishers with the
Lean Publishing process. Lean Publishing is the act of publishing an
in-progress ebook using lightweight tools and many iterations to get reader
feedback, pivot until you have the right book and build traction once you do.

© 2020 - 2021 Christian Nunciato

Contents

Welcome! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . i

Part 1: Foundations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Chapter 1: Introducing Pulumi . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Infrastructure: it’s complicated . . . . . . . . . . . . . . . . . . . . . . . . 4
What is infrastructure as code? . . . . . . . . . . . . . . . . . . . . . . . . 7
What is Pulumi? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Why should I use Pulumi? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Chapter 2: Your first Pulumi program . . . . . . . . . . . . . . . . . . . . . . 33

Building a serverless cloud notifier . . . . . . . . . . . . . . . . . . . . . . 33
Creating the project and stack . . . . . . . . . . . . . . . . . . . . . . . . . 34
Understanding the new project layout . . . . . . . . . . . . . . . . . . . . 34
Writing the code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Deploying the application . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Updating the stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Browsing the stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Tidying up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Chapter 3: Projects and stacks . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Monitoring a website’s uptime serverlessly . . . . . . . . . . . . . . . . . 38
CONTENTS

Creating the project and stack . . . . . . . . . . . . . . . . . . . . . . . . . 39

Thinking in projects and stacks . . . . . . . . . . . . . . . . . . . . . . . . 39
Developing the application . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Taking stock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Making the program configurable . . . . . . . . . . . . . . . . . . . . . . . 40
Adding a production stack . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Stepping back, and looking ahead . . . . . . . . . . . . . . . . . . . . . . . 41
Tidying up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Chapter 4: Configuration and secrets . . . . . . . . . . . . . . . . . . . . . . 42

A quick recap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Introducing Pulumi config . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Configuring with more than just strings . . . . . . . . . . . . . . . . . . . 43
Introducing Pulumi secrets . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Keeping secrets secret . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Configuring with AWS environment variables . . . . . . . . . . . . . . . . 43
Updating and deploying the production stack . . . . . . . . . . . . . . . . 44
Tidying Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Appendix A: Setting Things Up . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Welcome!

This content is not available in the sample book. The book can be purchased on
Leanpub at http://leanpub.com/pulumi.
Part 1: Foundations

This content is not available in the sample book. The book can be purchased on
Leanpub at http://leanpub.com/pulumi.
Chapter 1: Introducing Pulumi

This chapter covers:

• Infrastructure as code: what it is and why you should care

• How Pulumi is like (and unlike) other infrastructure-as-code tools

• The parts of Pulumi, what they do, and how to use them

• The typical Pulumi workflow, end to end with a simple project

Easy things should be easy, and hard things should be possible.

— Larry Wall, creator of Perl

As a developer, I’ve never quite loved having to deal with infrastructure.

By infrastructure, I mean the underlying machinery of computing: the rack-

mounted servers, virtual machines, networks, storage — most of it usually ends
up getting in my way, and at best is a distraction from what I really care about,
which is building and shipping web applications. In an ideal world, I’d just write
my app code, push my commits to GitHub, and sit back happily with the beverage
of my choice while the rest of the process just worked, and the infrastructure
magically took care of itself.

The trouble, of course, is that I’m a web developer, and you can’t get very far
with a web application without some kind of infrastructure. So for the majority
Chapter 1: Introducing Pulumi 3

of my career, I’ve had to contend with this reality, and it hasn’t always been fun.
Sometimes it has. But mostly, not so much.

But after years of frustration and toil, here’s what I’ve learned: with the right set
of tools, managing infrastructure can actually be a delightful experience, even
for a cranky developer like me. Pulumi, it turns out, is one of those tools.

Pulumi is an open-source command-line tool and software-development kit

(SDK) that lets you build, deploy, and manage cloud applications and infrastruc-
ture with general-purpose programming languages like TypeScript, C#, Python,
and Go. With Pulumi, you can build just about anything that can be built with
the cloud today, from simple static websites and serverless applications to vast
constellations of distributed microservices, all managed with code, using the
languages and tools that you know, love, and use every day. Pulumi belongs to
a class of tools designed to enable infrastructure as code, and in this book, you’ll
learn it from the ground up, by building a number of cloud-native applications
with TypeScript and deploying them into the Amazon Web Services (AWS) cloud.

Depending on your background, though, you might just be wondering why a tool
like Pulumi even exists in the first place. Why would anyone want to write code to
manage infrastructure? Isn’t it easier just to configure computers by hand? And
why should using a general-purpose language like TypeScript matter? Doesn’t
that make the process even more complicated?

Good questions all, and I’m glad that you asked them. Let’s begin, then, by taking
a step back and having a look at what led to the need for infrastructure as code to
begin with. And then later, you’ll meet Pulumi, and get a sense of what it is that
makes it so different.
Chapter 1: Introducing Pulumi 4

Infrastructure: it’s complicated

The cloud is a great and powerful thing: limitless computing available on demand,
and usable in so many ways it’s almost impossible to count them.

It’s also a huge, complex, and intimidating beast, and using it effectively can be
surprisingly difficult.

As a newcomer, just approaching the cloud can be overwhelming, if only because

of how much of the cloud there is today, and how many providers and services
there are to choose from. (I work with this stuff every day, and I can hardly keep
track of it all, myself.) AWS alone has close to two hundred individual services,
many of them obscurely named, confusingly priced, and with so many knobs and
switches it’s like staring at the cockpit of an airliner. And even if you happen to
know your way around, it’s still incredibly easy to get lost in all the complexity.

For example, imagine you’re a developer like me — comfortable building web

applications, but maybe not so comfortable managing servers. You like solving
problems with technology, though, and you’re a bit of an entrepreneurial soul as
well, so one day, in a flash of creative brilliance, you wake up with an idea for a
new online venture: a hyperlocal web service aimed at helping dog-owners and
dog-walkers get connected. (I’ll leave the name of this new venture to you; like
many a programmer, I’m awful with names.)

As you sketch out the details of this nascent little project, the application itself
seems fairly straightforward: to start, all you’ll need are a web app and a database,
so you opt to keep it simple and go with what you know: Express.js for the
application, say, and MySQL for the database. Easy enough.

For the infrastructure, though, you’re in much murkier territory. You know
you’ll need at least one server to host the application, and that a single server
Chapter 1: Introducing Pulumi 5

should probably suffice. But beyond that nebulous requirement — again, since
infrastructure isn’t your specialty — you aren’t quite sure how best to proceed.

But you’re committed, and AWS seems as safe a choice as any, so you decide to
roll forward and give it a shot. And on the whole, things go pretty well: with a
few button clicks, and a few hours spent sifting through docs and configuring
a new virtual machine, your shiny new dog-walking service is live, and people
are signing up. It’s an exciting time, both for you and for many a neighborhood
pooch. And before long, the service actually becomes rather popular.

So popular, in fact, that your little machine’s beginning to struggle to keep

up with demand. So in an effort to distribute the load a bit better, you move
the Express app onto a virtual machine of its own, leaving the database on the
original — moving the database would mean downtime — and after a few more
hours spent configuring the second machine (based on a shady recollection of
what you did for the first), you’re all set. Or so you think.

A few months later, maybe, you get an email from an angry customer claiming
the website is down, and indeed you immediately confirm that’s the case — and
not just down, but gone: both virtual machines have somehow vanished from the
AWS Console, leaving you no choice but to build them all over again, from scratch
(and right now), to save your fledgling business.

Or maybe you’re faced with a different problem: the website’s become so popular
that you seem to be spending all of your time dealing with infrastructure —
spinning up new servers, patching old ones, rotating logs, and so on — and no
time developing new features for the site, which is, of course, the whole reason
you got into this project in the first place.

And this is just one website. Imagine trying to manage two or three others like
it, all by hand, using only the browser and the command line. And now, imagine
ten, or twenty. It’s a losing proposition: beyond the smallest of scales, managing
Chapter 1: Introducing Pulumi 6

servers by hand becomes a full-time job, and sooner or later, without some kind
of automation, it’s practically impossible.

And at any scale, you’re constantly faced with other annoyances:

• Hand-crafted servers are opaque. You can’t look at AWS Console, for
example, and easily discern the state of a given machine — what’s installed
on that machine, which versions of an application it’s currently hosting,
which upstream services the application relies on, and so on. The need for
this kind of information comes up a lot more often than you might think,
and to get it, you usually have to go poking around on the command line.

• Hand-crafted servers are unique snowflakes. Just like your laptop, a man-
ually configured machine is the product of countless ad hoc mutations over
time, which means you can’t just stamp out another copy when you need
one. And even if you could, any change to one of the copies would have to be
made to all of them, which is tedious, error-prone, and not the sort of work
most of us would enjoy doing with our time.

• We humans are awesome, but we mess up — a lot. We click the wrong

buttons in dashboards, we make disastrous mistakes on the command line,
we stumble under pressure, and our memories are terrible. Not to mention
that we can only do one thing at a time. Everything computers are good at,
we aren’t. It’s just how it is.

But here’s the thing: while it’s true that we humans aren’t very good at managing
computers by hand, we are pretty good at describing how a computer (or a lot of
computers) ought to be configured. It might take me the better part of a month,
for example, to provision and configure a hundred servers running my massively
popular dog-walking website — but it only it only takes me a few moments to
write I want a thousand servers running my dog-walking website, and only a few
moments more to express that in code, and let the computers handle the work
of provisioning and configuration for me.
Chapter 1: Introducing Pulumi 7

What is infrastructure as code?

Infrastructure as code (IaC) is the practice of using code in combination with

specialized tools to produce some infrastructural outcome. In the previous sec-
tion, the outcome was pretty simple: to stand up a couple of virtual machines,
one running an application and the other a database, and to have them both
be properly configured to communicate with one another and be accessible on
the web. In other scenarios, it might be much more complex, involving dozens,
hundreds, or thousands of cloud resources working together to deliver some
globally distributed service like Twitter or Facebook. Ultimately, the goal of IaC
is to help you deliver software reliably and safely at any scale, and the best way
to do that is to let you express what you want, in some sort of text-based form,
and use the tools of IaC to turn that expression into reality.

Most IaC tools fall into one of two categories. Configuration management tools
focus on managing the software and settings of an existing computer — a virtual
machine, say, or a “bare-metal” (i.e., physical) server installed in a data center.
These tools typically run on their target computers directly, as executable pro-
grams, and you can think of them as software-based stand-ins for the kinds of
tasks you might perform at the command-line: installing packages like Node.js,
creating user accounts, writing configuration files, or fetching source code to up-
date a web application. Popular configuration management tools include Ansible
(https://ansible.com), Chef (https://chef.io), Puppet (https://puppet.com), and
SaltStack (https://saltstack.com).

Provisioning tools, on the other hand — Pulumi falls into this category — are
responsible for creating cloud infrastructure from scratch. Their job is to com-
municate with cloud providers like AWS on your behalf, and you can think of
them like stand-ins for what you might do in the AWS console: creating virtual-
machine instances or database clusters, modifying domain-name settings, and
so on. These tools target your cloud provider of choice, and generally run either
Chapter 1: Introducing Pulumi 8

on your computer or as part of a continuous-delivery pipeline. Popular provision-

ing tools include Pulumi of course, Terraform (https://www.terraform.io), and
AWS CloudFormation (https://aws.amazon.com/cloudformation).

Both types of tools have their rightful place your automation toolbox, and both
operate on a couple of common, fundamental principles:

• The code you write is declarative. Whether you’re writing in plain text, YAML,
or JavaScript, you’re describing what you want your infrastructure to be, not
how the tool should do it. Unlike a shell script that codifies an imperative
set of steps — do this, then this, then this — infrastructure-as-code declares
simply, I want this, and the tool figures out how to effect that reality.

• The tool operates idempotently. Given some declarative code as input, the
tool produces consistent output, regardless of how many times you run
it with that same code. Like a multiply() function that always returns 12
given a 6 and a 2, an IaC tool produces an equally reliable and repeatable
result, free from unexpected side-effects, and changing only what happens
to change in the code from one run to the next.

Likewise, both types of tools generally follow a similar workflow:

1. you write some code that declares the end state that you wish to achieve,

2. you run that code with a tool that knows how to interpret and translate it,
and

3. the tool computes what needs to be done, issuing the appropriate com-
mands on the target.

Importantly, though, in order to do its work safely, the tool also needs to know
what already exists. If it didn’t — to return to our dog-walking example —
Chapter 1: Introducing Pulumi 9

it’d stand up two new virtual machines on every run, violating the principle of
idempotency we just established (and racking up lots of AWS charges in the
process). To do things right, IaC tools must incorporate the concept of state,
which you can think of as a point-in-time snapshot of your infrastructure as
of the last time the tool successfully ran. This way, the tool can skip creating
resources that already exist, or change only certain properties of them, doing
only the work that’s necessary to drive the target to the new desired state.

Figure 1.1 shows the parts of a typical IaC workflow and how they all come
together.

Figure 1.1: The high-level components of infrastructure as code. IaC tools like Pulumi evaluate your code,
compare the result with what currently exists, drive your infrastructure to some desired state, recording that
state as the new, now current one.

If you’re new to this practice, it can take some getting used to. But the advantages
are more than worth the effort. Once you start driving your infrastructure with
code, you’ll find it difficult to go back to doing so manually. And for teams and
organizations that need to be able to ship software often and safely, there really
Chapter 1: Introducing Pulumi 10

is no better way.

Still, it can be challenging. With many of these tools, the learning curve can be
steep, especially when you’re trying to learn the tool itself, its unique language,
and the conventions of infrastructure-as-code all at the same time. And since
managing infrastructure has historically fallen under the umbrella of operations,
most of these tools were built by and for operational specialists, so they model
their domains in ways that may make sense to an operator, but leave others
— application developers, programmers from other disciplines, hobbyist coders
— generally lost. Despite how simple it might’ve seemed on the surface, our
little dog-walking app would actually require both classes of IaC tool in order
to be fully automated: a provisioning tool to spin up its virtual machines, and a
configuration management tool run separately afterward to manage the software
installed on both of them. Not so simple after all.

So what do you do? You want to be able to manage your infrastructure as code,
but the tools of the trade are decidedly working against you. Let’s turn now to
Pulumi to see how it can help.

What is Pulumi?

Pulumi is an open-source infrastructure-as-code platform that helps you create

and manage cloud applications and infrastructure. In some ways, it’s a lot like
other provisioning tools in that it’s powered by a command-line interface (CLI)
that runs on multiple platforms (macOS, Linux, and Windows), and its main job
is to translate the code that you write into running cloud software.

But it’s there that Pulumi begins to diverge from the others in some important
ways:
Chapter 1: Introducing Pulumi 11

• With Pulumi, you write code in a high-level programming language that

you choose yourself, not in a tool-specific one. In this book, you’ll use
TypeScript, but as of this writing, Pulumi also supports JavaScript, Python,
Go, and the .NET Core family of languages, including C#, F#, and Visual
Basic.

• Pulumi ships with an extensive set of language SDKs — npm packages for
Node.js, PyPi for Python, NuGet for .NET, and so on — that model the cloud
in a consistent, rich, and idiomatic way, allowing you to program at high
levels of abstraction.

• By default, Pulumi uses the free Pulumi Service to track the state of your
infrastructure across projects and environments, which other tools tend
leave it to you to manage that on your own. The Service is optional, but
incredibly helpful, so we’ll be using it in this book (and learn more about
it in chapter 3).

These are some of the features that most distinguish Pulumi. We’ll take a first
look at them in a moment, and put them to good use over the course of this book.
Additionally, it can also help to gain a quick understanding of a few of the ideas
behind Pulumi.

Understanding Pulumi

Pulumi is a constantly evolving open-source project with a large community and

dozens of active contributors. But it’s nevertheless guided by a few fundamental
principles.

Easy things are easy

In describing the design goals of the Perl programming language, Larry Wall, its
creator, said something that’s always stuck with me: “Easy things should be easy,
Chapter 1: Introducing Pulumi 12

and hard things should be possible.”

I haven’t written much Perl, myself. But most of us would probably agree that a
well-designed API of any kind should do exactly that: make it easy to accomplish
the kinds of tasks we do most often, while allowing us to handle the more
complicated ones when we need to.

It’s one of Pulumi’s guiding principles as well, and you can see it in the way
it builds in valuable, often overlooked features like state management, secrets
management (for managing passwords, keys, and the like), and straightforward
configuration — all with the help of the Pulumi service, along with useful APIs
aimed at getting things done.

Driven by general-purpose programming languages

Most infrastructure-as-code tools have you declare your resources individually

with blocks of static, structured text — JSON, YAML, and the like. This definitely
works, and seems easy enough on the surface. But over time, as a project grows,
you’ll often find that you need more control and flexibility than these formats
can give you. What if you wanted to run three app servers in production, but only
one in test? Or name your resources dynamically, using a third-party library or
an HTTP service? While some tools do support simple mechanisms like loops or
string interpolation, managing any sort of real complexity with statically written
text soon becomes an exercise in frustration.

Modern programming languages make this immeasurably easier. With Pulumi,

since you’re writing in your language of choice, you can use all of the facilities
available for that language and its ecosystem, including variables, loops, condi-
tional logic, functions, classes, modules, and package managers, and with the
help of modern IDEs, you can easily refactor your programs as you go. You’ll see
all of this at work in the chapters ahead.
Chapter 1: Introducing Pulumi 13

By and for developers

Built by a team of engineers from Microsoft with backgrounds in developer tools,

languages, and compilers, Pulumi is the first infrastructure-as-code tool built
with the needs and expectations of application developers in mind, and with the
goal of making it easier for anyone who can write a little code to take advantage of
the cloud. As long as you’re reasonably comfortable in at least one programming
language, can run a few commands in a terminal window, and are willing to spend
a little time learning what may be a few new cloud concepts, you’ve got all you
need to pick up start using Pulumi to program the cloud.

Using Pulumi: A end-to-end walkthrough

Let’s combine all we’ve covered up to now and use Pulumi to do something real
— well, semi-real, at least; you’ll build an application of your own in the next
chapter. For now, let’s just walk through a simple Pulumi project together from
start to finish, just to give you a sense of what the end-to-end workflow typically
looks like. The task at hand is ambitious, but achievable: a one-page website
deployed on AWS, purpose-built to deliver the programmer’s all-time favorite
greeting.
Chapter 1: Introducing Pulumi 14

Figure 1.2: A wireframe of the single-page website we’ll build and deploy to AWS with Pulumi.

On AWS, a common way to manage static websites is with the Simple Storage
Service (S3) (https://aws.amazon.com/s3/). With S3, you can store files of any
kind in what’s called a bucket, which you can think of as a uniquely named,
unlimited-capacity folder in the cloud. Since a website (a static one, anyway) is
ultimately just a collection of files in a folder, and S3 offers built-in support for
serving the contents of a bucket as a website, an S3-based website a good fit for
this kind of project.

So in this walkthrough, we’ll:

• Generate a new project with the Pulumi CLI,

• Write the code to define an S3 bucket and a home page,
• Run that code with Pulumi to provision the bucket and configure it as a
website, and finally,
• Verify the result.

These steps align with the workflow of pretty much every Pulumi project, as
illustrated in Figure 1.3. Whether you’re building a simple website like this one or
Chapter 1: Introducing Pulumi 15

a complex deployment of an infrastructure platform consisting of thousands of

globally distributed resources, it’s always the same: write the code, run Pulumi
to turn it into cloud infrastructure, and verify the result. (Technically, the third
step is optional, but always a good idea — ideally with some automated testing,
which you’ll learn more about in part 3).

Figure 1.3: A typical Pulumi workflow: Write some infrastructure code, run Pulumi, and verify the result aligns
with what you expected.

As we go, don’t worry about understanding every last detail; we’ve got the
rest of the book to explore everything in depth. At this point, it’s enough to
understand the broad strokes: what the steps are, what happens at each one,
and how they relate to one another to produce the intended result. Beyond that,
you might also keep an eye out for the ways that Pulumi applies the principles
of infrastructure-as-code that we’ve identified: declarative code, idempotently
applied, and backed by some form of persistent state.

Let’s get started.

Generating a new Pulumi project

The easiest way to begin a new Pulumi project is with the pulumi command-line
tool (CLI). Since in this book, we’ll mainly be using using TypeScript and AWS,
we’ll use the pulumi new command as follows:

$ pulumi new aws-typescript

Lots more new-project templates are available for different languages and cloud
providers, and you’ll learn how to write your own templates in part 3, when
Chapter 1: Introducing Pulumi 16

we explore the many ways of packaging and sharing Pulumi projects. After
prompting you for a few details about this one, the command completes, leaving
you with a couple of project configuration files, a package.json file for managing
the project’s dependencies, and an index.ts file containing the TypeScript code
for a minimal Pulumi program that happens to create an S3 bucket.

Writing the code

Now let’s take a look at the contents of that program. Listing 1.1 shows what’s
inside.

Listing 1.1: A Pulumi program that creates a storage bucket on Amazon S3.

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

2
3 const bucket = new aws.s3.Bucket("hello-world");

1 Imports the @pulumi/aws library for Node.js.

3 Declares a new S3 bucket using that library.

If you’ve worked with TypeScript, the first line should look pretty familiar: it just
imports the open-source @pulumi/aws SDK for Node.js, which was installed with
npm when we ran pulumi new. This package contains most of the JavaScript and
TypeScript APIs you’ll use to manage the resources of the AWS cloud, including
the s3 module, which defines the TypeScript Bucket class.

The second line is worth examining a bit more closely, both for what it does
as well as what it doesn’t. It creates an instance of the Bucket class, passing a
name to use for the actual bucket resource, and since we’re in TypeScript, this
is probably what you’d expect. But the program doesn’t appear to do anything
with that instance; there doesn’t seem to be any sort of .create() method being
called anywhere. How does Pulumi know to create an actual S3 bucket?
Chapter 1: Introducing Pulumi 17

We’ll come back to that in a moment. For now, let’s add a bit more code to round
out the program by configuring the bucket to behave like a website. The following
listing shows how that’s done.

Listing 1.2: The same program, extending the S3 bucket to serve a static website.

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

2
3 const bucket = new aws.s3.Bucket("hello-world", {
4 website: {
5 indexDocument: "index.html"
6 }
7 });
8
9 const homepage = new aws.s3.BucketObject("index.html", {
10 bucket: bucket,
11 acl: aws.s3.PublicReadAcl,
12 content: `
13 <html>
14 <body>Hello, world.</body>
15 </html>
16 `,
17 contentType: "text/html"
18 });
19
20 export const url = bucket.websiteEndpoint;

4 Adds a property to the Bucket that designates it as a website.

9 Declares an S3 BucketObject named index.html for the home page of the website.
10 Associates the BucketObject to the Bucket instance.
11 Assigns public read access to the BucketObject, making it accessible to anyone
on the internet.
12 Specifies the HTML content of the home page.
20 Captures the URL of the website, computed by AWS, as an exported variable.

Again we construct a new instance of a Pulumi TypeScript class, this one a

Chapter 1: Introducing Pulumi 18

BucketObject, which we’ll use to contain the content of the home page. Because
we want our visitors to be able to view the page in a browser, we need to tell
AWS to make it publicly accessible, so we provide an acl property (ACL stands
for access-control list) using a TypeScript enum 1 , a handy way to be sure you’re
using a valid value, rather than just a raw string that could be easily mistyped.
For the home page itself, we simply supply a snippet of HTML, but we could
also have written a more elaborate home page in a separate file and imported
it programmatically, using the built-in Node.js FileSystem module — another
example of the benefits of using a real programming language. For example:

Listing 1.3: The same program, using an HTML file read from the local filesystem.

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

2 import * as fs from "fs";
3
4 const bucket = new aws.s3.Bucket("hello-world", {
5 website: {
6 indexDocument: "index.html"
7 }
8 });
9
10 const homepage = new aws.s3.BucketObject("index.html", {
11 bucket: bucket,
12 acl: aws.s3.PublicReadAcl,
13 content: fs.readFileSync("./index.html").toString(),
14 contentType: "text/html"
15 });
16
17 export const url = bucket.websiteEndpoint;

2 Imports Node.js’s built-in fs module.

13 Reads the index.html file from the current directory.

Finally, the last line of the program exports the websiteEndpoint property of the
1 https://www.typescriptlang.org/docs/handbook/enums.html
Chapter 1: Introducing Pulumi 19

bucket instance — the URL of the website — which AWS will compute and expose
to Pulumi once the bucket is created and configured. There’s a good bit of detail
packed into that statement, but for now, it’s enough to note that by exporting
this value, Pulumi will print the value of that property to the terminal, to give us
something to navigate to.

With that, we’re ready to deploy.

Deploying to AWS

In addition to serving as a helpful way to bootstrap a new project, the Pulumi CLI
is responsible for converting your code into running cloud infrastructure. You’ll
generally divide your time with Pulumi between your editor, writing programs,
and the CLI, running commands like the ones we’ll look at next:

• pulumi preview, which tells you what your program would do, if you were to
deploy it, and

• pulumi update (or pulumi up, for short), which performs an actual deploy-
ment.

When you’re comfortable enough with a program to give it a trial run, you can
open your terminal, change to your project folder, and run pulumi preview. The
output below shows the result for our working example.
Chapter 1: Introducing Pulumi 20

Previewing the infrastructure to be created for the hello-world program.

1 $ pulumi preview
2
3 Previewing update (dev):
4 Type Name Plan
5 + pulumi:pulumi:Stack hello-dev create
6 + ├─ aws:s3:Bucket hello-world create
7 + └─ aws:s3:BucketObject index.html create
8
9 Resources:
10 + 3 to create

5 The dev stack resource.

6 The S3 Bucket resource.
7 The S3 BucketObject resource.

There are several interesting things to note about this output. First, after evalu-
ating the code, Pulumi’s determined that it needs to create three new resources
— which is interesting, considering we only declared two. The aws:s3:Bucket and
aws:s3:BucketObject look familiar, but where’d the pulumi:pulumi:Stack come
from?

We’ll cover stacks in much more detail in chapter 3, but you can think of them as
logical groupings of cloud resources intended to make it easier for you to manage
your deployments. You can create as many stacks as you like for a given project,
name them however you like, and configure them independently of one another.
By default, Pulumi offers to create a dev stack for every new project; we accepted
that default when we ran pulumi new.

It looks like this hypothetical dev stack would contain two actual cloud resources
after all, which sounds about right. Now let’s see what happens when we run the
update for real.
Chapter 1: Introducing Pulumi 21

Deploying the hello-world program for the first time.

1 $ pulumi up
2
3 Updating (dev):
4 Type Name Status
5 + pulumi:pulumi:Stack hello-dev created
6 + ├─ aws:s3:Bucket hello-world created
7 + └─ aws:s3:BucketObject index.html created
8
9 Outputs:
10 url: "hello-world-ae6198e.s3-website-us-west-2.amazonaws.com"
11
12 Resources:
13 + 3 created
14
15 Duration: 18s
16
17 Permalink: https://app.pulumi.com/cnunciato/hello/dev/updates/1

5 The newly created dev stack.

6 The S3 bucket containing our website.
7 The home page of the website.
10 The URL of the website, exported using the bucket’s websiteEndpoint property.
17 A link to the update record in the Pulumi Console.

The output suggests Pulumi did what was expected: All three resources have now
been created, and the export statement we declared in the program has produced
a url property listed under Outputs. Navigating to that URL reveals the final
product, in all its minimalist glory.
Chapter 1: Introducing Pulumi 22

Figure 1.4: The finished product, now deployed as a static website on AWS.

You’ll find the source code for this example, along with all others con-
tained in this book, on GitHub at https://github.com/thepulumibook.

Now let’s conclude this excursion by following the Permalink to the Pulumi
Console. The Console is the web interface for the Pulumi Service, which Pulumi
uses by default to manage the state of your infrastructure, along with all of your
projects, stacks, and integrations with third-party services like GitHub (which
you’ll learn more about in part 3, when we explore continuous integration and
delivery). Let’s do that now.

Verifying the result

Our project has a permanent home in the Pulumi Console. There, you’ll see a
history of all of the changes made to your each of your Pulumi stacks, along with
the resources that belong to each one. Figure 1.5 shows the Resources tab of the
hello project’s dev stack, which lists the bucket and bucket object, each with a
link to their respective locations in the AWS Management Console.
Chapter 1: Introducing Pulumi 23

Figure 1.5: The Pulumi Console, a free service that helps you manage your Pulumi projects and stacks.

There, you can inspect the properties of the bucket, as shown in Figure 1.6.
Chapter 1: Introducing Pulumi 24

Figure 1.6: The bucket and bucket object, as seen in the AWS Management Console.

Reviewing what happened

We covered a lot, so let’s briefly review.

We began with the pulumi new command, which generated a Pulumi project for us,
along with a complete, ready-to-run TypeScript program defining an S3 bucket.
We added a few lines of code to turn that bucket into a website, ran pulumi preview
to get a glimpse of the cloud resources the program would create, and ran pulumi
up to create them. And finally, we verified the result by viewing the website
in a browser, the project and stack in the Pulumi Console, and the resources
themselves on AWS. If we wanted, we could make a change to the homepage, run
pulumi up, and have that change deployed instantly, or even delete the website
Chapter 1: Introducing Pulumi 25

entirely with another command, pulumi destroy, which you’ll use to tidy up after
the project you build in the next chapter.

You also learned that by default, the Pulumi CLI uses the free Pulumi Service to
manage the state of your infrastructure over time, and that the Pulumi Console
offers a convenient way to keep track of your projects, stacks, and cloud resources
all in one place. You’ll learn much more about the Service and Console in the
chapters ahead.

A peek under the hood

Let’s expand our working model now into a more detailed one to carry with you as
you move forward. Again, don’t worry if you don’t understand everything here;
we’ll return to this model repeatedly throughout the book. But you’ve learned
enough at this point that it’d be good to get a more complete sense of how Pulumi
really works.

Figure 1.7 zooms in on the Pulumi CLI to reveal a couple of new but important
parts: the language host, which actually runs the code that you write, and the
resource provider, which handles communicating with the cloud service to create,
read, update, or delete the resources you define in your Pulumi programs.
Chapter 1: Introducing Pulumi 26

Figure 1.7: A closer look at the Pulumi CLI. Pulumi passes your code to a language host (such as Node.js), waits to
be notified of resource registrations, assembles a model of your desired state, and calls on the resource provider
to produce that state by communicating directly with cloud services like AWS.

Earlier I mentioned we’d come back to the part about how Pulumi knew to create
the S3 bucket and homepage, given that all we’d done was instantiate a couple of
objects. That’s where the language host comes in. When we ran pulumi preview
and later pulumi up, the Pulumi CLI determined that since our chosen language
was TypeScript, our program code should be run with Node.js. (If we’d written
a program in Python, it would’ve used Python; if C#, .NET Core, and so on.) So
Pulumi launched Node implicitly, passed it our code, and waited to be notified of
resource declarations.

Our calls to construct new Bucket() and new BucketObject() instances were exactly
that — declarations to Pulumi of a desire to have these two resources exist in our
infrastructure stack. Importantly, the resources weren’t actually created on AWS
in that moment; rather, their details were simply captured by Pulumi, collected,
and compared with our existing state. Since that state was empty (as new projects
are), Pulumi computed that these resources should be created, so it assembled a
list of operations to perform — create a new bucket, configure the bucket as website,
create a new file in that bucket — and passed that list to the resource provider,
Chapter 1: Introducing Pulumi 27

which translated them into API requests to perform on the AWS service itself.
When the work of the resource provider was complete and our resources created,
Pulumi updated our stack’s state accordingly, saving it back to the Pulumi Service
for use on the next run.

Every Pulumi project follows the very same workflow, from simple websites
like this one, to serverless web applications, to the most complex cloud-native
deployments involving hundreds or thousands of resources: one tool, one work-
flow, and one language, start to finish. And it’s only a short hop from here to the
Git-driven workflow I mentioned at the beginning of the chapter — which, as it
happens, you’ll learn how to do in part 3.

Why should I use Pulumi?

Let’s round out this chapter by highlighting a few of Pulumi’s unique strengths.

Building on what you know

We all come to the cloud with different backgrounds and experiences. I men-
tioned I’m a web developer; you might be, too — or you might be a data scientist
looking to move a computational workload into AWS, or a release engineer
working to improve the way your company ships software. Whoever you are,
if you’re reading this book, there’s a pretty good chance you aren’t an expert
in cloud operations, and an equally good chance you’re at least moderately
comfortable with at least one high-level programming language, whatever that
language happens to be.

Pulumi was built with this in mind. Rather than expect you to learn a new
discipline, or vendor- or tool-specific language, it lets you start with a language
Chapter 1: Introducing Pulumi 28

you already know well, and go from there. In practice, that means you can
generally hit the ground running, applying the skills you already have to what
might well be a totally new domain for you. (As it was for me.)

It also means being able to bring all of the benefits of your chosen language
and its ecosystem along for the ride. As you’ve seen, a Pulumi program is just
a regular program — a Node.js script, a Go program with a main entrypoint —
so you can use whatever organizational constructs, language features, or third-
party libraries you like with Pulumi, too.

And if you’re a fan, as I am, of tools like Visual Studio Code, you’ve probably come
to appreciate features like type checking, IntelliSense, and head’s up documen-
tation that make it easier to explore and use APIs you may still be learning. Figure
1.8 shows what it’s like to develop with the Pulumi SDK for Node.js, where code
hinting and inline documentation help to keep you productive and on the happy
path.

Figure 1.8: Deep support for programming languages enables syntax highlighting, code completion, inline
documentation, automated refactoring, and more, with popular tools like Visual Studio Code.
Chapter 1: Introducing Pulumi 29

Meeting you where you are

As a developer, I’m used to working at a fairly high level. The languages I use
most often are built to help me work productively, and at a level of abstraction
that allows me to get things done. TypeScript, for instance, is a great fit for web
development work. C, on the other hand, would not be — it’s too low-level, too
“close to the metal”. If building web applications meant having to learn and use
C every day, there’d be a lot fewer web applications in the world, and a lot fewer
web developers, too. It’d just be too difficult for most people to bother with.

And yet that’s what a lot of infrastructure tools seem to expect from us — to
descend from our high-level cruising altitudes back down to sea level just to
manage some infrastructure.

Pulumi’s use of general-purpose, high-level languages like JavaScript flips this

upside down, bringing infrastructure up to a level that developers are not only
able to work with, but comfortable doing so. We’ve already seen how with a few
lines of TypeScript, you can deploy a static website — but as you’ll see as we move
through this chapter and beyond, even a much more complex application needn’t
require a whole lot more code than that.

When you want a bucket, you can ask for a bucket — but when you want a
serverless REST API, you can also just ask for a serverless REST API, and the
Pulumi SDK will likely be there to help you. That that a REST API might consist of
a dozen or more cloud resources — a network, gateway, multiple cloud functions
and access policies, etc. — is an implementation detail that Pulumi knows you
probably don’t care all that much about, so long as it works, is appropriately
secure, and you can customize and extend it when you need to. Easy things are
easy, and hard things are possible.
Chapter 1: Introducing Pulumi 30

Using the whole cloud

A lot of developer-focused cloud tools do a few things really well, like help you
build and deploy static websites and distribute them globally, or make it easy
to add serverless API endpoints for those websites with a little configuration.
Many of these tools are truly great at what they do — but when you find yourself
hitting the edges of what they’re capable of, like when it’s time to add a relational
database, or a horizontally scalable API service, you usually have figure those
things out on your own, which often means having to go back to clicking buttons
in a dashboard, or using some other tool to set those additional components up
for you.

The Pulumi SDK gives you a rich set of language-specific APIs that aim to model
the whole cloud, consistently and idiomatically — all major clouds, by the way;
not just AWS — which means you can write programs that create static websites,
serverless APIs, database clusters, or containerized services as easily as you can
a single S3 bucket — and even wire them all together within the scope of a single
program.

Built for complexity

In this book, we’re focused mainly on learning Pulumi by building small appli-
cations, but it’s important to know that Pulumi is made to handle the needs of
large organizations as well, where responsibilities are often split between teams
of developers and operators, and where operators are charged with the task of
building secure, reliable cloud platforms of their own that can handle constant
change and unbounded scale.

General-purpose programming languages are a powerful solution to this prob-

lem, in part because of how good they are at handling complexity. JavaScript,
Chapter 1: Introducing Pulumi 31

for example, is not only a flexible and productive language with a massive com-
munity and ecosystem; it also lends itself well to modern software-engineering
practices like linting, testing, debugging, and refactoring, among others — prac-
tices that help us keep our code under control as our systems grow larger and
ever more complicated. Nothing is worse than having to work in a codebase
that’s huge, brittle, and hard to understand. With Pulumi, you’ll manage your
infrastructure as software, refactoring as you go to keep things clean and under
control.

Programs must be written for people to read, and only incidentally for
machines to execute.
— Harold Abelson and Gerald Jay Sussman, Preface to the Second Edition,
Structure and Interpretation of Computer Programs

You’ve learned quite a bit about Pulumi in this chapter, and I hope you’re excited
to keep learning more. Now would be a good time to take a break with your own
beverage of choice before heading into chapter 2, where you’ll build your first
cloud-native application with Pulumi.
Chapter 1: Introducing Pulumi 32

Summary

• Pulumi is an open-source infrastructure-as-code platform that lets you

build, deploy, and manage cloud applications and infrastructure with mod-
ern programming languages like TypeScript, Python, C#, and Go.

• Pulumi is made up of three parts: a command-line tool that runs on all

major platforms; a collection of language-specific SDKs that model the
resources of the cloud; and the optional Pulumi Service and Console, which
help you manage your projects, stacks, and infrastructure state more effec-
tively.

• With Pulumi, you write programs that declare cloud resources as collections
of objects, and Pulumi translates those programs into running cloud soft-
ware.

• With the Pulumi CLI, you can generate new projects, preview infrastructure
changes before you make them, and modify your infrastructure safely and
idempotently.

• Pulumi is built to make developing cloud applications and infrastructure as

accessible as possible, while at the same time addressing the complex needs
of large teams and organizations.
Chapter 2: Your first Pulumi program