IDP Pattern: One ESC environment per lifecycle stage

Description

This pattern involves creating dedicated Pulumi ESC (Environments, Secrets, and Configuration) environments for each lifecycle stage of your application deployment pipeline, such as development, staging, and production. Each stage has its own environment with stage-specific configuration and secrets.

When to use this pattern

• Always-on services: When running SaaS applications, social media sites, or online stores with one primary instance
• Reliability focus: When uptime and reliability are critical business requirements
• Careful rollouts: When you need to test configuration changes through stages before production
• Single-instance applications: When you have one main production deployment rather than multiple customer instances

When NOT to use this pattern

• Multi-tenant applications: When you deploy separate instances for different customers
• Rapid iteration: When you need to deploy frequently without formal staging processes
• Cost-sensitive projects: When maintaining multiple environments is too expensive

How to use this pattern

This pattern works well with Pulumi ESC’s composition to share common configuration while allowing stage-specific overrides.

Example

Consider a SaaS application deployed across three stages:

# environments/development.yaml
values:
  stage: "development"
  app:
    replicas: 1
    logLevel: "debug"
    database:
      host: "dev-db.example.com"
      ssl: false
  secrets:
    apiKey: "dev-api-key"

# environments/staging.yaml
values:
  stage: "staging"
  app:
    replicas: 2
    logLevel: "info"
    database:
      host: "staging-db.example.com"
      ssl: true
  secrets:
    apiKey: "staging-api-key"

# environments/production.yaml
values:
  stage: "production"
  app:
    replicas: 5
    logLevel: "warn"
    database:
      host: "prod-db.example.com"
      ssl: true
  secrets:
    apiKey: "prod-api-key"

Your Pulumi program can compose with shared base configuration:

# pulumi.yaml for production deployment
name: web-app
runtime: nodejs

environment:
  - base-config
  - production

This allows consistent base configuration while enabling stage-specific customization.

Related patterns

• IDP Pattern: One ESC environment per service - Can be combined for service-stage matrices
• IDP Pattern: One ESC environment per team - Can be combined for team-stage matrices
• IDP Pattern: Composable environments - For sharing base configuration across stages