Skip to content
Tutorials Center
My learning

Topics

Lesson 1 of 36 ยท Getting Started

What Is Pulumi? Infrastructure as Code in Real Languages

Learn what Pulumi is, how it describes cloud infrastructure with TypeScript, Python, Go or C#, and how it differs from Terraform, CloudFormation and manual clicking.

Pulumi is an infrastructure as code (IaC) tool. You write a normal program in a language such as TypeScript, Python, Go, C#, Java or YAML, and Pulumi turns it into a set of cloud resources: buckets, networks, databases, Kubernetes clusters, DNS records. When the program changes, Pulumi works out the difference between what exists and what you now describe, and changes only what is needed.

This lesson explains the idea, the vocabulary and the moving parts before you install anything.

What runs on this site. Pulumi itself needs the pulumi CLI, language runtimes and cloud credentials, so it cannot run in your browser. Every Pulumi program in this tutorial is shown as read-only code. Next to it you get small runnable JavaScript stand-ins: toy versions of the ideas (desired state, diffing, outputs, secrets) that you can edit and run here. They are labelled as stand-ins, and they never talk to a cloud. Command output is shown only where it is stable.

The problem Pulumi solves

Creating infrastructure by clicking in a cloud console is fast the first time and painful afterwards. Nobody remembers which boxes were ticked, a second environment needs the same clicks again, and there is no review step. Infrastructure as code fixes this by storing the description of your infrastructure in files, under version control, where it can be reviewed, tested and repeated.

Tools differ in how you write that description:

Approach Example tools You write
Domain-specific language Terraform, OpenTofu HCL, a purpose-built config language
Data files CloudFormation, Bicep, ARM JSON/YAML or a small templating language
General-purpose language Pulumi, AWS CDK TypeScript, Python, Go, C#, Java

Pulumi's bet is that real languages give you real tools: loops, functions, classes, package managers, IDE autocomplete, type checking and unit tests, without learning a second language.

Your first look at a Pulumi program

Here is a complete program that creates an S3 bucket. It is real Pulumi code, shown read-only.

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

const bucket = new aws.s3.BucketV2("site-assets", {
  tags: { team: "web" },
});

export const bucketName = bucket.id;

Three ideas are already visible:

  1. new aws.s3.BucketV2(...) declares a resource. The first argument is its Pulumi name, the second its inputs.
  2. You do not call a "create bucket" API. You declare that a bucket should exist.
  3. export publishes a stack output, a value other programs and people can read after the deployment.

The same program in Python reads almost the same:

Python
import pulumi
import pulumi_aws as aws

bucket = aws.s3.BucketV2("site-assets", tags={"team": "web"})

pulumi.export("bucket_name", bucket.id)

How a deployment works

When you run pulumi up, four things happen. The diagram shows the loop.

flowchart LR
  A["Your program<br/>(TypeScript, Python, ...)"] --> B["Language host<br/>runs the program"]
  B --> C["Pulumi engine<br/>compares goal vs. state"]
  C --> D["Providers<br/>call cloud APIs"]
  D --> E["State<br/>records what exists"]
  E --> C

The engine never reads your code directly. The language host runs it and reports the resources it registers.

  • The language host runs your program. Each new Resource(...) registers a desired resource with the engine.
  • The engine compares the registered resources with the state, the record of what Pulumi created last time.
  • It builds a plan (create, update, replace, delete) and, after you confirm, asks providers to carry it out.
  • Providers are plugins that talk to a cloud, such as AWS, Azure, Google Cloud or Kubernetes.
  • The new state is saved so the next run can compare against it.

Stand-in: desired state versus actual state

This toy engine captures the heart of IaC. You describe what you want; it computes the actions. Edit desired and run again.

JS Stand-in: a tiny plan engine

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that you never wrote "update assets" or "delete logs". The program is a description; the engine derives the verbs. This is called a declarative model, even though you write it in an imperative language.

Stand-in: why a real language helps

Because the description is ordinary code, you can generate it. One loop produces three environments:

JS Stand-in: generating resources with a loop

Press Run (or Ctrl + Enter) to see the console output here.

No output.

In HCL you would reach for for_each; in Pulumi it is a plain for loop or map.

Pulumi compared with other tools

  • Terraform/OpenTofu use HCL and a large provider ecosystem; Pulumi can even consume Terraform providers through a bridge, which is why Pulumi covers most clouds. See Terraform for the HCL side.
  • CloudFormation/Bicep are cloud-specific. Pulumi is multi-cloud with one workflow.
  • AWS CDK also uses real languages but generates CloudFormation templates; Pulumi talks to the cloud directly through its engine and providers.
  • Ansible configures machines; Pulumi provisions the infrastructure those machines live in.

Pulumi Cloud and the open-source CLI

The CLI and engine are open source (Apache 2.0). Pulumi Cloud is an optional hosted service that stores state, encrypts secrets, shows deployment history and manages teams. You can instead keep state in a file, an S3 bucket or another object store (see State and Backends later in the course).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a Pulumi program describe?

    Pulumi is declarative: you register resources and the engine derives the create, update and delete actions.
  2. 2. What is the role of a provider?

    Providers are plugins for AWS, Azure, Google Cloud, Kubernetes and many others.
  3. 3. Which statement about Pulumi's languages is true?

    Supported languages include TypeScript, Python, Go, C#, Java and YAML, with the full language available.
  4. 4. Where does Pulumi remember what it created?

    The state records resources and their properties so the engine can compare it with the new desired set.

Summary

  • Pulumi is infrastructure as code in general-purpose languages, with a declarative result.
  • A program registers resources; the engine compares them with the state and plans create, update, replace or delete steps.
  • Providers are plugins that call cloud APIs; state records what exists.
  • The CLI is open source; Pulumi Cloud is an optional hosted backend.
  • On this site, Pulumi code is read-only and the JavaScript stand-ins are teaching toys.

Next: Install Pulumi and Create Your First Project