Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 36 ยท Config and Secrets

Pulumi Config per Environment: Dev, Staging and Prod

Design environment-specific Pulumi configuration: per-stack files, defaults in code, typed config objects, feature flags, copying configuration between stacks and avoiding drift between environments.

The goal of environment configuration is one codebase with small, visible differences between dev, staging and prod. This lesson shows patterns that keep those differences in config rather than in if statements, and how to avoid the usual drift problems.

One codebase, one file per stack

YAML
# Pulumi.dev.yaml
config:
  aws:region: us-east-1
  shop:instanceType: t3.micro
  shop:replicas: "1"
  shop:enableWaf: "false"
YAML
# Pulumi.prod.yaml
config:
  aws:region: eu-central-1
  shop:instanceType: m6i.large
  shop:replicas: "4"
  shop:enableWaf: "true"

The program stays identical and reads the values:

TypeScript
const config = new pulumi.Config();
const instanceType = config.require("instanceType");
const replicas = config.requireNumber("replicas");
const enableWaf = config.getBoolean("enableWaf") ?? false;

Put defaults in one place

Two places may hold defaults: the Pulumi.yaml schema or the code. Pick one per key.

YAML
# Pulumi.yaml
config:
  replicas:
    type: integer
    default: 1

or

TypeScript
const replicas = config.getNumber("replicas") ?? 1;

Defaults make dev stacks short (only list what is different) while prod lists everything important explicitly, which makes review easy: the prod file is the specification.

A typed settings object

Reading config values scattered across the program makes it hard to see what the program needs. Gather them once:

TypeScript
interface Settings {
  instanceType: string;
  replicas: number;
  enableWaf: boolean;
  allowedCidrs: string[];
}

function loadSettings(): Settings {
  const c = new pulumi.Config();
  const settings: Settings = {
    instanceType: c.get("instanceType") ?? "t3.micro",
    replicas: c.getNumber("replicas") ?? 1,
    enableWaf: c.getBoolean("enableWaf") ?? false,
    allowedCidrs: c.getObject<string[]>("allowedCidrs") ?? [],
  };
  if (settings.replicas < 1) throw new Error("replicas must be >= 1");
  if (pulumi.getStack() === "prod" && !settings.enableWaf) throw new Error("prod requires enableWaf");
  return settings;
}

const settings = loadSettings();

A guard like the last one encodes policy in code: prod without a WAF fails the preview, not the incident review.

Environment tiers instead of stack names

Avoid if (pulumi.getStack() === "prod") all over. Translate the stack once into a flag or tier and branch on that, or better, drive the behaviour by config:

TypeScript
const isProd = config.getBoolean("production") ?? false;
const multiAz = isProd;
const backupRetentionDays = isProd ? 30 : 1;

Then pulumi config set production true in the prod stack. The code no longer cares what you name your stacks (prod-eu, prod-us, canary).

Keeping stacks in sync

Environments drift when someone sets a value in prod and forgets dev. Helpful habits:

  • Compare stack files in review: diff Pulumi.dev.yaml Pulumi.prod.yaml.
  • Copy a stack's config when creating a new one: pulumi stack init staging --copy-config-from dev.
  • Make a new key required in every stack with require, so a missing value fails every stack's preview.
  • Use a small script or CI check to assert that every stack file defines the keys you expect.

Different values per region

Multi-region deployments usually mean one stack per region (prod-eu, prod-us) with the same code and a different aws:region. Shared settings that both regions need (domain names, feature flags) can live in an ESC environment imported by both stacks (ESC Environments), so you set them once.

Secrets per environment

Each stack encrypts its own secrets with its own key. Prod's secrets provider can be a KMS key that only the production deploy role may use, while dev uses a cheaper one. A developer can then preview and update dev without ever being able to decrypt prod secrets (Secrets in Config).

Stand-in: merge defaults with stack values

JS Stand-in: defaults plus stack overrides

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

No output.

Stand-in: spot drift between stack files

JS Stand-in: compare stack configs

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

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where should environment differences live?

    Config per stack keeps one codebase and makes differences reviewable.
  2. 2. Why prefer a 'production' flag over checking the stack name everywhere?

    A config flag decouples behaviour from naming.
  3. 3. What does pulumi stack init staging --copy-config-from dev do?

    It copies configuration, not resources or state.
  4. 4. How can a guard in code protect prod?

    Failing the program fails the preview before anything changes.

Summary

  • Use one codebase with one config file per stack; put differences in config.
  • Keep defaults in one place and gather settings into a typed object with validation.
  • Drive behaviour with flags such as production, not scattered stack-name checks.
  • Copy config when creating stacks and compare files to prevent drift.
  • Each stack has its own secrets key, so access to dev does not imply access to prod.

Next: Pulumi ESC: Environments, Secrets and OIDC