Pulumi Basics

Intro

Pulumi is an IAC (Infrastructure As Code) tool, similar to Terraform, that uses standard programming languages like TypeScript to manage cloud infrastructure.

These notes will all relate to using Pulumi with AWS and TypeScript.

Setup

During setup you will need to provide AWS credentials to an IAM account that has programmatic access (can provision AWS services via the SDK/CLI).

This user will have an Access Key ID and a Secret Access Key that Pulumi can use to authenticate API requests to AWS.

AWS > IAM user access keys

Terminology

Project - A project is the equivalent of a git repo. The entire project including configurations for all environments and regions is contained within.

Stack - A stack is a configuration for a specific environment dev, test, prod etc.

Project Structure

If I am building a full stack application, will I create two projects (one for front, one for back) or are they both contained within one Pulumi project?

You have the flexibility to structure your Pulumi infrastructure as code (IaC) project in a way that best fits your needs. Here's how you can approach it:

Single Pulumi Project

• Unified Deployment: If your frontend and backend are closely coupled and you prefer to manage and deploy them together, you can include both in a single Pulumi project. This approach simplifies your project structure and makes it easier to coordinate changes across the entire stack.

• Simplified Management: A single project means a single codebase and state file, which can simplify version control and state management.

  Multiple Pulumi Projects

• Independent Lifecycles: If your frontend and backend have different release cycles or are managed by different teams, separating them into two Pulumi projects can provide clearer boundaries.

• Modularity and Reusability: Splitting projects can make your infrastructure code more modular. For instance, if you have multiple frontends consuming the same backend API, you might reuse the backend project across different frontend projects.

• Isolation: Separate projects can help in isolating the state and reducing the risk of unintended interactions between frontend and backend resources.

Best Practices to Consider

• Stacks for Environments: Regardless of whether you choose a single or multiple projects, you can use Pulumi stacks to manage different environments (e.g., development, staging, production).

• Inter-Project Dependencies: If you split projects, you can export outputs from one project (like the backend API endpoint) and import them into another, ensuring they can still interact seamlessly.

• Team Collaboration: Consider your team's structure. If different teams handle the frontend and backend, separate projects might align better with your development process.

Project Files

A Pulumi project contains three key files.

Pulumi.yaml

This is the project file: 📘 Pulumi Docs > Projects

and looks like this:

Pulumi.yaml

name: some-project-name
runtime:
  name: nodejs
  options:
    packagemanager: npm
description: A description of your project.
config:
  pulumi:tags:
    value:
      pulumi:template: aws-typescript

tip

tip Note the runtime which is specified here. This is not the runtime of the front or back of the application you are building. This is the runtime environment for Pulumi to run in while it programmatically generates and destroys resources.

A Pulumi project is any folder that contains a Pulumi.yaml project file. At runtime, the nearest parent folder containing a Pulumi.yaml file determines the current project.

The project file specifies which runtime to use and determines where to look for the program that should be executed during deployments. Supported runtimes are nodejs, python, dotnet, go, java, and yaml.

Project files also contain metadata about your project. The project file must begin with a capital P, although either .yml or .yaml extension will work.

Pulumi.STACK.yaml

The stack configuration file: 📘 Pulumi Docs > Configuration

IE Pulumi.dev.yaml, Pulumi.prod.yaml etc etc.

The stack configuration file allows you to change variables depending on the environment. Reference a different database, a different API, AWS EC2 instance size or region, etc etc.

pulumi.dev.yaml

config:
  aws:region: us-east-1

index.ts

The Pulumi program that defines your stack resources.

import * as pulumi from '@pulumi/pulumi';
import * as aws from '@pulumi/aws';
import * as awsx from '@pulumi/awsx';

// Create an AWS resource (S3 Bucket)
const bucket = new aws.s3.Bucket('my-bucket');

// Export the name of the bucket
export const bucketName = bucket.id;

Commands

• pulumi new: creates a new project using a template
• pulumi stack: manage your stacks (at least one is required to perform an update)
• pulumi config: configure variables such as keys, regions, and so on
• pulumi up: preview and deploy changes to your program and/or infrastructure
• pulumi preview: preview your changes explicitly before deploying
• pulumi destroy: destroy your program and its infrastructure when you’re done

Custom Resource vs Component Resource

📘 Pulumi Docs > Concepts > Resources

Resources represent the fundamental units that make up your cloud infrastructure, such as a compute instance, a storage bucket, or a Kubernetes cluster.

All infrastructure resources are described by one of two subclasses of the Resource class. These two subclasses are:

• CustomResource: A custom resource is a cloud resource managed by a resource provider such as AWS, Microsoft Azure, Google Cloud or Kubernetes.
• ComponentResource: A component resource is a logical grouping of other resources that creates a larger, higher-level abstraction that encapsulates its implementation details.

Environment Variables

You could use standard node environment variables. But Pulumi has an elegant way to handle stack specific variables.

pulumi config set myVariable myValue

and then reference the variable with

const config = new pulumi.Config();
const myVariable = config.require('myVariable');

tip

Remember, if you set variables this way, they are set to the stack, not the whole project.

Comments

Recent Work

Basalt

basalt.software

Free desktop AI Chat client, designed for developers and businesses. Unlocks advanced model settings only available in the API. Includes quality of life features like custom syntax highlighting.

Learn More

BidBear

bidbear.io

Bidbear is a report automation tool. It downloads Amazon Seller and Advertising reports, daily, to a private database. It then merges and formats the data into beautiful, on demand, exportable performance reports.

Learn More