Guide ·

Pulumi for a small site: infrastructure as Python

Written by an AI. Claude, Anthropic's AI model, wrote this guide, working with athinktank in Claude Code, from the Pulumi program that runs skunkyard.com. An open-source starter built from it is aws-static-site.

Pulumi lets you describe cloud resources in an ordinary programming language, then creates, changes, or deletes them to match. This site's bucket, CDN, certificate, DNS records, and security headers are about 270 lines of Python. The command-line tool is open source under the Apache 2.0 license and costs nothing.

Why write infrastructure as code

The five ideas you need

IdeaWhat it isOn this site
ProjectA folder with a Pulumi.yaml that names the program and its languageinfra/, Python run through uv
ProgramThe code that declares resourcesinfra/stack.py, imported by __main__.py so tests can import it too
StackOne deployed copy of the program, with its own settings in Pulumi.<stack>.yamlOne stack, prod
StatePulumi's record of what it last deployed, with each resource's IDA file in a private, versioned S3 bucket
Config and secretsPer-stack settings; secrets are encrypted in the stateThe domain name, and a passphrase kept as a GitHub secret

The commands

On this site, a person never runs pulumi up. GitHub Actions runs it on every push to main, so every change has a log. A pull request runs pulumi preview; see Preview infrastructure changes in a pull request.

A resource, in Python

Each resource is an object. Pulumi works out the order to create them from the values they pass to each other. This is the certificate for the site and its www name:

cert = aws.acm.Certificate(
    "cert", domain_name=DOMAIN, subject_alternative_names=[WWW], validation_method="DNS"
)

The DNS records that prove you own the domain take their names from cert.domain_validation_options. Those values don't exist until AWS creates the certificate, so Pulumi creates the certificate first.

Keep the state yourself, for free

By default, Pulumi stores state in Pulumi Cloud, the vendor's hosted service. You can keep it yourself instead. Pulumi calls this a DIY backend. This site points Pulumi at an S3 bucket:

pulumi login s3://skunkyard-pulumi-state-<account-id>

With your own state, you also keep these jobs:

The bootstrap problem

Pulumi needs a state bucket and a way to sign in to AWS before it can run. Those can't come from Pulumi itself. This site creates them once by hand, with a short CloudFormation template, infra/bootstrap.yaml. It makes:

Everything else lives in the Pulumi program, including every other role. The deploy role may manage any role or policy named skunkyard-*, so a new feature's roles deploy with the feature, not through another hand-run update.

Test the program without AWS

Pulumi's test mocks stand in for AWS, so the program runs in a second with no account. This site's tests check that:

The mock replaces each resource and lookup with a function you write:

class Mocks(pulumi.runtime.Mocks):
    def new_resource(self, args):
        return f"{args.name}-id", dict(args.inputs)

    def call(self, args):
        if args.token == "aws:route53/getZone:getZone":
            return {"zoneId": "Z0MOCK", "name": "skunkyard.com"}
        return {}

pulumi.runtime.set_mocks(Mocks(), project="skunkyard", stack="test", preview=False)

What it costs

ItemCost
Pulumi command-line toolFree, Apache 2.0
State in your own S3 bucketA few cents a month at most
Runs in GitHub ActionsFree minutes on most plans

Problems hit along the way