Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 36 ยท Getting Started

Install Pulumi and Create Your First Project

Install the Pulumi CLI, choose a backend, log in, scaffold a project with pulumi new and understand every file it creates, with read-only commands and runnable stand-ins.

To work with Pulumi on your own machine you need three things: the pulumi CLI, a language runtime for the language you prefer, and credentials for the cloud you target. This lesson walks through installation, logging in to a backend and generating a first project with pulumi new.

Commands here are real and run on your computer, not on this site. The terminal blocks are read-only. The runnable pieces are labelled stand-ins.

Install the CLI

Pick the method for your system:

Terminal
# macOS or Linux with Homebrew
brew install pulumi/tap/pulumi

# Windows with winget
winget install pulumi

# Linux or macOS with the install script
curl -fsSL https://get.pulumi.com | sh

Check the installation:

Terminal
pulumi version

It prints a version such as v3.xxx.x; the number depends on when you install. Updating is the same command you used to install it (for example brew upgrade pulumi).

Install a language runtime

Pulumi runs your program with the normal runtime of your language:

Language You need Package manager
TypeScript / JavaScript Node.js (a current LTS) npm, yarn, pnpm
Python Python 3.9 or newer pip (a virtualenv is created for you)
Go Go toolchain Go modules
C# / F# .NET SDK NuGet
Java JDK and Maven or Gradle Maven Central
YAML nothing extra n/a

Pick where state lives: log in

Pulumi must store state somewhere. pulumi login chooses the backend:

Terminal
# Pulumi Cloud (opens a browser or asks for a token)
pulumi login

# A folder on your own machine, no account needed
pulumi login --local

# A bucket you own (state stays in your cloud account)
pulumi login s3://my-pulumi-state

For learning, pulumi login --local is the quickest, because it needs no account. State then lives under ~/.pulumi. A later lesson (State and Backends) compares all options. With a local or bucket backend you also choose a passphrase that protects secrets; set it in the environment variable PULUMI_CONFIG_PASSPHRASE to avoid being prompted.

Cloud credentials

Pulumi does not store cloud credentials. Providers read them from the usual places: for AWS, the same credential chain the AWS CLI uses (environment variables or ~/.aws); for Azure, az login; for Google Cloud, gcloud auth application-default login. If aws sts get-caller-identity works in your shell, the Pulumi AWS provider will work too.

Scaffold a project

pulumi new creates a project from a template. Create an empty folder and run:

Terminal
mkdir hello-pulumi && cd hello-pulumi
pulumi new aws-typescript

You are asked for a project name, a description, a stack name (use dev) and some configuration such as the AWS region. Other template names follow the same pattern: aws-python, azure-go, gcp-csharp, kubernetes-typescript, aws-yaml. Run pulumi new with no argument to browse the list. Use pulumi new --generate-only if you want the files without installing dependencies yet.

What was created

For aws-typescript you get roughly this layout:

Text
hello-pulumi/
  Pulumi.yaml          project definition
  Pulumi.dev.yaml      configuration of the "dev" stack
  index.ts             your program
  package.json         npm dependencies
  tsconfig.json        TypeScript settings
  .gitignore

Pulumi.yaml marks the folder as a project:

YAML
name: hello-pulumi
description: My first Pulumi project
runtime:
  name: nodejs
  options:
    packagemanager: npm

Pulumi.dev.yaml holds the stack's settings:

YAML
config:
  aws:region: us-east-1

And index.ts is the template's starter program, typically one bucket:

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

const bucket = new aws.s3.BucketV2("my-bucket");

export const bucketName = bucket.id;

Commit all of these files except what .gitignore excludes (such as node_modules). Pulumi.dev.yaml belongs in Git because it describes how that stack is configured; secrets inside it are encrypted.

Stand-in: reading a project definition

The CLI first finds Pulumi.yaml by walking up from your current folder. This stand-in imitates that check on a tiny in-memory file system.

JS Stand-in: find the project file

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

No output.

That last case is the same failure you see when you run a Pulumi command in the wrong folder.

Stand-in: parsing project fields

A project file is plain YAML. Here a simplified parser pulls out the fields the CLI cares about:

JS Stand-in: parse Pulumi.yaml fields

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

No output.

The real parser is a full YAML reader, and it enforces more rules (a project name may contain letters, digits, hyphens, underscores and periods).

Run the first deployment (preview)

Do not run pulumi up yet unless you want a real bucket; the next lessons cover it. To look first, run:

Terminal
pulumi preview

The preview lists the resources that would be created, for example the stack itself and one bucket, and changes nothing.

Troubleshooting first runs

  • "no Pulumi.yaml project file found": you are not inside a project folder.
  • "error: no stack selected": run pulumi stack select dev or pulumi stack init dev.
  • Missing credentials (such as "no valid credential sources found"): fix your cloud login; Pulumi only reports what the provider says.
  • Passphrase prompts: with a non-Pulumi-Cloud backend, set PULUMI_CONFIG_PASSPHRASE.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command logs in with state stored on your own machine, no account needed?

    pulumi login --local selects the local filesystem backend.
  2. 2. Which file marks a folder as a Pulumi project?

    Pulumi.yaml holds the project name and runtime. Pulumi.dev.yaml is the dev stack's configuration.
  3. 3. Where does Pulumi get cloud credentials from?

    Pulumi does not manage cloud credentials itself; providers read them like the cloud's own CLI does.
  4. 4. What does pulumi preview do?

    Preview is a dry run of an update.

Summary

  • Install the CLI, the runtime for your language and cloud credentials.
  • pulumi login picks a backend: Pulumi Cloud, --local, or a bucket.
  • pulumi new <template> scaffolds a project: Pulumi.yaml, a stack config file, your program and dependency files.
  • Commit the project files; use pulumi preview to look before you deploy.

Next: Project Layout: Pulumi.yaml and Stack Files