Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 36 ยท Projects and Practice

Project: A Multi-Environment Platform with Stack References

Design a platform of Pulumi projects and environments: micro-stacks connected by stack references, per-environment config, promotion order, config consistency checks and a dependency-aware rollout.

One stack that holds the whole company is slow to preview, risky to change and impossible to share between teams. The opposite extreme, hundreds of tiny stacks with tangled references, is just as painful. This project builds a middle path: a small platform of three projects, each deployed to three environments, connected by stack references and promoted in a fixed order.

Nothing here needs a cloud account to understand, but the real stacks do. The Pulumi code is read-only; the stand-ins check what goes wrong most often in multi-environment setups: inconsistent config keys and a wrong deployment order.

The layout

flowchart LR
  subgraph "project: network"
    N1["dev"]
    N2["staging"]
    N3["prod"]
  end
  subgraph "project: data"
    D1["dev"]
    D2["staging"]
    D3["prod"]
  end
  subgraph "project: app"
    A1["dev"]
    A2["staging"]
    A3["prod"]
  end
  N1 --> D1 --> A1
  N2 --> D2 --> A2
  N3 --> D3 --> A3

Three projects, three environments: nine stacks. Arrows are stack references between the same environment.

Why split by project:

  • Different lifecycles. The network changes rarely; the app changes daily. Separate stacks keep previews small and blast radius limited.
  • Different owners. A platform team owns network and data; product teams own app.
  • Different permissions. Only the platform pipeline needs rights to change the VPC.

Why not split further: every extra stack adds references to maintain, and each reference is a coupling. Split where a boundary already exists.

Stack references

A stack exports values; another stack reads them through a StackReference:

TypeScript
// network/index.ts
export const vpcId = vpc.vpcId;
export const privateSubnetIds = vpc.privateSubnetIds;

// data/index.ts
const org = "acme";
const env = pulumi.getStack();                       // "dev", "staging", "prod"
const network = new pulumi.StackReference(`${org}/network/${env}`);

const subnetIds = network.requireOutput("privateSubnetIds") as pulumi.Output<string[]>;
const vpcId = network.requireOutput("vpcId") as pulumi.Output<string>;

export const dbEndpoint = db.address;
export const dbSecretArn = secret.arn;

Points to remember:

  • References are by name: org/project/stack. The consumer always reads the latest deployed outputs, so deploy producers first.
  • Use requireOutput (fails clearly if missing) rather than getOutput.
  • Outputs are a public contract between projects. Add outputs freely; renaming or removing them is a breaking change for consumers.
  • Secrets in outputs stay secret in the consumer.
  • Permissions: reading a stack reference needs read access to the producer stack's state. Scope CI roles accordingly.

Alternatives for loose coupling: look up resources by tag or name with provider get... functions, or write shared values to a parameter store and read them from there. Choose stack references when you want an explicit, visible dependency; choose lookups when teams must not know each other's Pulumi layout.

Config per environment

Every stack has its own Pulumi.<stack>.yaml. Differences should be in config, not in code branches:

YAML
# app/Pulumi.dev.yaml
config:
  aws:region: eu-central-1
  app:replicas: "1"
  app:domain: dev.example.com
  app:featureFlags: '{"newCheckout":true}'

# app/Pulumi.prod.yaml
config:
  aws:region: eu-central-1
  app:replicas: "3"
  app:domain: example.com
  app:featureFlags: '{"newCheckout":false}'

When one environment lacks a key that another has, the program either fails at up (with require) or quietly uses a default and behaves differently in prod. A check in CI that compares key sets across stack config files catches this at PR time.

Node.js Stand-in: config consistency across environments

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

In CI, a Pulumi-aware version reads each Pulumi.<stack>.yaml, and the validators can be the same schema your program uses at startup.

Deployment order

The app stack reads outputs of data, which reads network. Deploying in the wrong order either fails (missing output) or, worse, deploys against old values. Describe the dependencies as data, compute an order, and detect cycles, which are a design bug.

Node.js Stand-in: deployment order and cycle detection

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

A promotion pipeline usually deploys all projects in dev, runs checks, then continues to staging and, after approval, prod. Alternatively each project has its own pipeline and a change to network triggers dependents. Pick one and document it.

Promotion in practice

  1. A change merges to main; CI deploys to dev automatically.
  2. Smoke tests and a policy scan run; a human or schedule promotes to staging.
  3. Staging soaks (integration tests, drift check); an approval gate protects prod.
  4. Every step uses the same commit and the same code; only config differs.
  5. If a stage fails, stop and fix forward or revert (see Safe Operations).

Use pulumi stack tag set to record the deployed git SHA in each stack, so you can see at a glance what runs where, and Pulumi Cloud's environments and secrets management (ESC) if you want shared configuration with inheritance instead of copying values between files.

Hygiene rules for platforms

  • Document each project's exports like an API: names, types, meaning.
  • Never read another team's stack by guessing names; publish a contract.
  • Keep fan-out small. A stack referenced by thirty others is a bottleneck; consider a parameter store for widely shared values.
  • Consistent naming of stacks (dev, staging, prod) lets code compute reference names from pulumi.getStack().
  • Policy packs and drift checks attach to environment groups, not individual stacks.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A stack reference reads which version of the producer stack's outputs?

    A stack reference reads the current recorded outputs, so producers must be deployed first.
  2. 2. Why prefer requireOutput over getOutput for essential values?

    Failing early with a precise message avoids confusing downstream errors.
  3. 3. What should differ between dev and prod stacks of the same project?

    Use one program and varying config, so what you test is what you ship.
  4. 4. A cycle appears in the stack dependency graph. What does it indicate?

    Cycles mean mutual dependency. Break them by moving shared parts into a lower-level project.

Summary

  • Split a platform into a few projects by lifecycle, owner and permissions, and deploy each to the same set of environments.
  • Stack references provide explicit, by-name links; outputs are a contract, so evolve them carefully.
  • Put environment differences in config and validate config consistency in CI.
  • Compute deployment order from the dependency graph and treat cycles as design bugs.
  • Promote the same commit through dev, staging and prod, with gates and checks in between.

Next: Practice: Reviewing and Fixing Pulumi Programs