Pulumi for a small site: infrastructure as Python
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 code is the record. Each change is a commit, so you can see who changed what, when, and why.
- You see a change before you make it. Pulumi compares the code with what it last deployed and lists what it would create, update, replace, or delete.
- You can rebuild it. If an account is lost, the same program builds the same site in a new one.
- You can test it. The program is Python, so ordinary unit tests can check it, such as "only the CDN may read the bucket."
The five ideas you need
| Idea | What it is | On this site |
|---|---|---|
| Project | A folder with a Pulumi.yaml that names the
program and its language | infra/, Python run through uv |
| Program | The code that declares resources | infra/stack.py,
imported by __main__.py so tests can import it too |
| Stack | One deployed copy of the program, with its own settings in
Pulumi.<stack>.yaml | One stack, prod |
| State | Pulumi's record of what it last deployed, with each resource's ID | A file in a private, versioned S3 bucket |
| Config and secrets | Per-stack settings; secrets are encrypted in the state | The domain name, and a passphrase kept as a GitHub secret |
The commands
pulumi previewruns the program and lists what would change. It changes nothing.pulumi upmakes the changes, then saves the new state.pulumi refreshreads the real resources and updates the state, for when someone changed something by hand.
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:
- Turn on bucket versioning. If the state file is damaged, you can restore an older copy.
- Keep the passphrase safe. It encrypts the stack's secrets. Without it, Pulumi can't read them.
- Know about the lock. During an operation, Pulumi writes a lock
file under
.pulumi/locks/in the bucket, so two runs can't change the stack at once. A role that only previews still needs to write and delete those files.
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:
- The Route 53 hosted zone for the domain.
- The state bucket.
- GitHub's OIDC sign-in provider, so GitHub Actions gets short-lived AWS credentials instead of stored keys.
- The role that deploys, trusted only by pushes to
main. - A permissions boundary that caps the pull request preview role at reading.
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:
- Missing pages return 404, not 200.
- Only CloudFront can read the bucket.
- The security headers follow OWASP.
- The deploy role trusts only
main, and writes to IAM only for roles and policies namedskunkyard-*. - The preview role trusts only pull requests, and can't change anything but Pulumi's lock files.
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
| Item | Cost |
|---|---|
| Pulumi command-line tool | Free, Apache 2.0 |
| State in your own S3 bucket | A few cents a month at most |
| Runs in GitHub Actions | Free minutes on most plans |
Problems hit along the way
- The first deploy failed to sign in. The role trusted the
repository by name, but GitHub sent an immutable subject that includes the owner's
and repository's numeric IDs. Look up yours with
gh api repos/OWNER/REPO/actions/oidc/customization/sub. - A preview has unknowns. Values that AWS assigns, such as a new
distribution's ID, show as unknown until
pulumi upcreates them.