Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 36 ยท Concepts and Stacks

Pulumi Stacks and Projects: Dev, Staging and Prod

Understand Pulumi stacks: isolated instances of a project for dev, staging and prod. Learn stack commands, fully qualified names, tags, and how to structure environments.

A project is the program and its metadata. A stack is one isolated instance of that program, with its own configuration, state and outputs. The same code deployed as stacks dev, staging and prod creates three independent sets of resources. This is Pulumi's answer to "how do I run the same infrastructure in several environments?".

Project versus stack

flowchart TD
  P["Project: web-platform<br/>(code + Pulumi.yaml)"] --> S1["Stack dev<br/>config + state"]
  P --> S2["Stack staging<br/>config + state"]
  P --> S3["Stack prod<br/>config + state"]
  S1 --> R1["resources in dev account"]
  S3 --> R3["resources in prod account"]

One program, three stacks. Each stack tracks only the resources it created.

A stack does not have to mean an environment. People also use stacks per developer (alice-dev), per region (prod-eu, prod-us), per customer or per pull request preview.

Stack commands

Terminal
pulumi stack init dev           # create a stack
pulumi stack ls                 # list stacks of this project
pulumi stack select prod        # make prod the current stack
pulumi stack                     # show the current stack and its resources
pulumi stack output             # outputs of the current stack
pulumi stack rm dev             # remove an empty stack
pulumi stack rename old new     # rename (changes resource URNs, see below)
pulumi stack graph graph.dot    # export the dependency graph
pulumi stack export > state.json    # raw state

Most commands accept -s <stack> (or --stack) so you can act on another stack without selecting it, which is safer in scripts.

Fully qualified stack names

On Pulumi Cloud a stack is identified as organization/project/stack, for example acme/web-platform/prod. On self-managed backends the form is organization/project/stack too, where the organization is the fixed word organization, so people usually write just prod. Use the full name when you reference a stack from another project (Stack Outputs and References).

Stack settings: Pulumi..yaml

Each stack's file stores configuration. The same code reads different values per stack:

YAML
# Pulumi.dev.yaml
config:
  aws:region: us-east-1
  web-platform:instanceCount: "1"
YAML
# Pulumi.prod.yaml
config:
  aws:region: eu-central-1
  web-platform:instanceCount: "4"
TypeScript
import * as pulumi from "@pulumi/pulumi";

const config = new pulumi.Config();
const instanceCount = config.getNumber("instanceCount") ?? 1;

// Inside the program you can also ask which stack you are in:
const stack = pulumi.getStack();      // "dev" or "prod"
const project = pulumi.getProject();  // "web-platform"

Config is covered in depth in Config Basics.

Stack tags and organization

Stacks can carry tags such as team=payments or tier=prod. Pulumi Cloud lets you filter by tag, and some are set automatically (for example pulumi:project, pulumi:runtime).

Terminal
pulumi stack tag set owner payments-team
pulumi stack tag ls

Naming and identity

Every resource in state has a URN (uniform resource name) built from the stack, project, type and name:

Text
urn:pulumi:prod::web-platform::aws:s3/bucketV2:BucketV2::assets

If you rename the stack or project, URNs change, and Pulumi would see all resources as new and the old ones as deleted. That is why pulumi stack rename and project renames need care; aliases (Resource Options) help migrate safely.

Stand-in: one program, several stacks

This stand-in runs the same function with different per-stack config and prints each stack's resource list, like three independent deployments.

JS Stand-in: one program, three stacks

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

No output.

Stand-in: why renaming a stack is dangerous

JS Stand-in: URNs change when names change

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

No output.

Good stack habits

  • Keep stack names short and stable; avoid renaming.
  • Do not copy-paste code per environment. Put differences in stack config, not in if (stack === "prod") forks scattered everywhere. A single well-named flag such as isProd is fine.
  • Use separate cloud accounts or subscriptions for prod and non-prod; a stack name is not a security boundary.
  • Select stacks explicitly in CI with --stack.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is a Pulumi stack?

    The same project can be deployed as many independent stacks.
  2. 2. Which command creates a new stack named staging?

    pulumi stack init creates it; pulumi stack select switches to it.
  3. 3. Why can renaming a stack be dangerous?

    The stack name is part of every resource's URN.
  4. 4. How do you read the current stack name inside a program?

    pulumi.getStack() (get_stack in Python) returns it.

Summary

  • A project is code plus metadata; a stack is an isolated instance with its own config, state and outputs.
  • Use pulumi stack init/select/ls/rm and -s to target stacks.
  • Differences between environments belong in per-stack config.
  • URNs include project and stack names, so renames need care.
  • Stacks are not security boundaries; use separate accounts for prod.

Next: Desired State, URNs and How Diffing Works