@egulatee/pulumi-stack-alias

Producer-side stack aliasing for Pulumi using lightweight proxy stacks. Consumers use standard StackReference (zero library dependency), while producers use this library to create alias stacks that re-export outputs from canonical stacks.

Problem

When managing infrastructure across multiple environments (dev, staging, prod), consumer projects need to reference shared infrastructure stacks. Traditional approaches either:

Force consumers to know which stack holds the real resources
Scatter mapping logic across every consumer project
Require complex consumer-side resolvers with library dependencies

The aliasing decision belongs with the producer (infrastructure project), not the consumer.

Solution: Producer-Controlled Proxy Stacks

Alias stacks re-export outputs from canonical stacks. Consumers use standard Pulumi StackReference with no library dependency. Producers use this library to create lightweight proxy stacks.

How It Works

infrastructure/shared    → canonical stack, exports real resources
infrastructure/dev       → proxy stack, re-exports outputs from shared
infrastructure/staging   → proxy stack, re-exports outputs from shared
infrastructure/prod      → canonical stack, exports real resources

Consumer uses standard Pulumi:

const stack = new pulumi.StackReference(`org/infrastructure/${pulumi.getStack()}`);
const vpcId = stack.requireOutput("vpcId");

Zero consumer dependencies! The consumer has no knowledge of aliasing. When application/dev deploys, it reads infrastructure/dev, which is a proxy stack that re-exports outputs from infrastructure/shared.

Installation

Producer projects only:

npm install @egulatee/pulumi-stack-alias

Consumer projects: No installation needed! Use standard Pulumi StackReference.

Usage

Producer Side (Infrastructure Project)

Create alias stacks that re-export outputs from canonical stacks:

Simple Alias

// infrastructure/index.ts
import { createStackAlias } from "@egulatee/pulumi-stack-alias";
import * as pulumi from "@pulumi/pulumi";

const config = new pulumi.Config();
const aliasTarget = config.get("aliasTarget");

if (aliasTarget) {
  // This is an alias stack — re-export outputs from target
  const alias = createStackAlias({
    targetProject: "infrastructure",
    targetStack: aliasTarget,
    outputs: ["vpcId", "endpoint", "clusterName"],
  });

  export const vpcId = alias.vpcId;
  export const endpoint = alias.endpoint;
  export const clusterName = alias.clusterName;
} else {
  // This is a canonical stack — create actual resources
  const vpc = new aws.ec2.Vpc("main", {
    cidrBlock: "10.0.0.0/16",
  });

  export const vpcId = vpc.id;
  export const endpoint = pulumi.output("https://api.example.com");
  export const clusterName = pulumi.output("my-cluster");
}

Configure your stack files:

# infrastructure/Pulumi.shared.yaml
config:
  # No aliasTarget — this is the canonical stack

# infrastructure/Pulumi.dev.yaml
config:
  infrastructure:aliasTarget: shared

# infrastructure/Pulumi.staging.yaml
config:
  infrastructure:aliasTarget: shared

# infrastructure/Pulumi.prod.yaml
config:
  # No aliasTarget — this is a canonical stack (separate from shared)

Conditional Alias (Pattern-Based)

For automatic aliasing without config:

// infrastructure/index.ts
import { createConditionalAlias } from "@egulatee/pulumi-stack-alias";

const alias = createConditionalAlias({
  targetProject: "infrastructure",
  patterns: [
    { pattern: "*/prod", target: "prod" },
    { pattern: "*/staging", target: "shared" },
    { pattern: "*/dev", target: "shared" },
    { pattern: "*/*-ephemeral", target: "shared" },
  ],
  defaultTarget: "shared",
  outputs: ["vpcId", "endpoint", "clusterName"],
});

export const vpcId = alias.vpcId;
export const endpoint = alias.endpoint;
export const clusterName = alias.clusterName;

Simple API

Simplified API for common cases:

import { createSimpleAlias } from "@egulatee/pulumi-stack-alias";

const alias = createSimpleAlias("infrastructure", "shared", ["vpcId"]);
export const vpcId = alias.vpcId;

Consumer Side (Application Project)

Use standard Pulumi StackReference — no library dependency:

// application/index.ts
import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

// Standard Pulumi StackReference — no special library needed!
const infraStack = new pulumi.StackReference(
  `${pulumi.getOrganization()}/infrastructure/${pulumi.getStack()}`
);

const vpcId = infraStack.requireOutput("vpcId");
const endpoint = infraStack.requireOutput("endpoint");

const subnet = new aws.ec2.Subnet("app-subnet", {
  vpcId: vpcId,
  cidrBlock: "10.0.1.0/24",
});

The consumer has zero knowledge of aliasing. When application/dev deploys:

Reads infrastructure/dev (a proxy stack)
Gets outputs (re-exported from infrastructure/shared)
No library dependency required!

Deployment Flow

Initial Setup

# Deploy canonical stacks (creates real resources)
pulumi up --stack shared
pulumi up --stack prod

# Deploy alias stacks (creates proxy outputs)
pulumi up --stack dev
pulumi up --stack staging

# Consumer deployments — no alias awareness needed
cd application && pulumi up --stack dev

Keeping Outputs Fresh

Alias stacks capture outputs at deploy time. When canonical stack outputs change, redeploy aliases:

# Update canonical stack
pulumi up --stack shared

# Sync alias stacks (fast — no real resources)
pulumi up --stack dev
pulumi up --stack staging

CI/CD Orchestration

Automate alias synchronization in CI/CD:

# .github/workflows/deploy.yml
jobs:
  deploy-canonical:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy shared stack
        run: pulumi up --stack shared --yes

  sync-aliases:
    needs: deploy-canonical
    runs-on: ubuntu-latest
    strategy:
      matrix:
        stack: [dev, staging]
    steps:
      - name: Sync alias stack
        run: pulumi up --stack ${{ matrix.stack }} --yes

Alias deployments are fast (seconds) since they create no real resources — just re-export outputs.

API Reference

`createStackAlias(config)`

Creates a stack alias that re-exports outputs from a target stack.

Parameters:

config.targetProject (string) - Target project name
config.targetStack (string) - Target stack name
config.targetOrg (optional string) - Target organization (defaults to current org)
config.outputs (string[]) - List of output names to re-export

Returns: AliasExports - Record of Pulumi Outputs

Example:

const alias = createStackAlias({
  targetProject: "infrastructure",
  targetStack: "shared",
  outputs: ["vpcId", "endpoint"],
});

export const vpcId = alias.vpcId;
export const endpoint = alias.endpoint;

`createConditionalAlias(config)`

Creates a conditional alias based on pattern matching.

Parameters:

config.targetProject (string) - Target project name
config.patterns (PatternRule[]) - Pattern matching rules (evaluated in order, first match wins)
config.defaultTarget (optional string) - Default target if no pattern matches
config.targetOrg (optional string) - Target organization (defaults to current org)
config.outputs (string[]) - List of output names to re-export

Returns: AliasExports - Record of Pulumi Outputs

Example:

const alias = createConditionalAlias({
  targetProject: "infrastructure",
  patterns: [
    { pattern: "*/prod", target: "prod" },
    { pattern: "*/dev", target: "shared" },
  ],
  defaultTarget: "shared",
  outputs: ["vpcId"],
});

`createSimpleAlias(targetProject, targetStack, outputs)`

Simplified API for creating aliases.

Parameters:

targetProject (string) - Target project name
targetStack (string) - Target stack name
outputs (string[]) - List of output names to re-export

Returns: AliasExports - Record of Pulumi Outputs

Example:

const alias = createSimpleAlias("infrastructure", "shared", ["vpcId"]);
export const vpcId = alias.vpcId;

`matchesPattern(pattern, project, stack)`

Pattern matching with wildcard support.

Wildcard rules:

* matches any value
*-suffix matches strings ending with -suffix
prefix-* matches strings starting with prefix-
exact matches exactly

Example:

import { matchesPattern } from "@egulatee/pulumi-stack-alias";

matchesPattern("*/dev", "myproject", "dev")        // true
matchesPattern("*/*-ephemeral", "app", "pr-123-ephemeral")  // true
matchesPattern("app-*/prod-*", "app-api", "prod-us")        // true

Pattern Format

Patterns follow the format: "projectPattern/stackPattern"

Examples:

"*/dev" - Any project, stack must be "dev"
"myproject/*" - Project must be "myproject", any stack
"*/*-ephemeral" - Any project, stack must end with "-ephemeral"
"app-*/prod-*" - Project must start with "app-", stack must start with "prod-"

Comparison with Other Approaches

Concern	Producer Redirect (v0.1.0)	Producer Proxy (v0.2.0)	Consumer Config
Who owns mapping	Producer ✓	Producer ✓	Consumer
Consumer library dependency	Yes	None ✓	Varies
Alias stack weight	Trivial (one pointer)	Light (output refs)	N/A
Output freshness	Always live ✓	Stale until redeployed*	Always live ✓
Consumer code	`resolveStackRef(...)`	`new StackReference(...)` ✓	Custom
CI/CD orchestration	Not needed	Recommended	Not needed

* Mitigated with CI/CD automation — alias deployments are fast (seconds)

Benefits

✅ Zero consumer dependencies - Consumers use standard Pulumi StackReference ✅ Producer-controlled - Infrastructure projects own aliasing decisions ✅ Type-safe - Full TypeScript support ✅ Flexible patterns - Wildcard pattern matching for conditional aliasing ✅ CI/CD friendly - Fast alias deployments (no real resources) ✅ Simple API - Three functions cover all use cases

Trade-offs

Pros:

Zero consumer library dependency
Standard Pulumi patterns
Simple mental model

Cons:

Alias stacks need redeployment when canonical outputs change (mitigated with CI/CD)
Slightly more operational overhead than redirect pattern (but eliminates consumer dependencies)

Use Cases

Shared Development Infrastructure

Deploy infrastructure once, route dev/staging to it:

const alias = createConditionalAlias({
  targetProject: "infrastructure",
  patterns: [
    { pattern: "*/prod", target: "prod" },
  ],
  defaultTarget: "shared",
  outputs: ["vpcId", "endpoint"],
});

Ephemeral PR Environments

Route ephemeral stacks to shared infrastructure:

const alias = createConditionalAlias({
  targetProject: "infrastructure",
  patterns: [
    { pattern: "*/*-ephemeral", target: "shared" },
    { pattern: "*/prod", target: "prod" },
  ],
  defaultTarget: "shared",
  outputs: ["vpcId"],
});

Multi-Region Deployments

Route regional stacks to regional infrastructure:

const alias = createConditionalAlias({
  targetProject: "infrastructure",
  patterns: [
    { pattern: "*/us-*", target: "us-east" },
    { pattern: "*/eu-*", target: "eu-west" },
  ],
  outputs: ["vpcId"],
});

Examples

See the examples directory for complete implementations:

Simple Alias - Basic proxy stack
Conditional Alias - Pattern-based aliasing

Migration Guide

From v0.1.0 (Redirect Pattern) to v0.2.0 (Proxy Pattern)

This is a breaking change — complete API rewrite.

Producer Changes

Before (v0.1.0):

// infrastructure/index.ts
const config = new pulumi.Config();
const aliasTarget = config.get("aliasTarget");

if (aliasTarget) {
  export const _canonicalStack = aliasTarget;
} else {
  export const vpcId = vpc.id;
}

After (v0.2.0):

// infrastructure/index.ts
import { createStackAlias } from "@egulatee/pulumi-stack-alias";

const config = new pulumi.Config();
const aliasTarget = config.get("aliasTarget");

if (aliasTarget) {
  const alias = createStackAlias({
    targetProject: "infrastructure",
    targetStack: aliasTarget,
    outputs: ["vpcId", "endpoint"],
  });

  export const vpcId = alias.vpcId;
  export const endpoint = alias.endpoint;
} else {
  export const vpcId = vpc.id;
  export const endpoint = /* ... */;
}

Consumer Changes

Before (v0.1.0):

import { resolveStackRef } from "@egulatee/pulumi-stack-alias";

const infraStack = resolveStackRef("infrastructure");
const vpcId = infraStack.apply(ref => ref.requireOutput("vpcId"));

After (v0.2.0):

// NO LIBRARY IMPORT NEEDED!
const infraStack = new pulumi.StackReference(
  `${pulumi.getOrganization()}/infrastructure/${pulumi.getStack()}`
);
const vpcId = infraStack.requireOutput("vpcId");

Migration Steps

Update package.json: Bump to @egulatee/pulumi-stack-alias@^0.2.0
Update producer code: Replace _canonicalStack exports with createStackAlias() calls
Update consumer code: Replace resolveStackRef() with standard new StackReference()
Remove consumer dependency: Uninstall @egulatee/pulumi-stack-alias from consumer projects
Redeploy all stacks: Alias stacks need one-time redeployment to export new outputs
Set up CI/CD: Add alias sync jobs to keep outputs fresh

Contributing

Contributions are welcome! Please see the GitHub issues for planned features and enhancements.

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
.github/workflows		.github/workflows
examples		examples
src		src
tests		tests
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

@egulatee/pulumi-stack-alias

Problem

Solution: Producer-Controlled Proxy Stacks

How It Works

Installation

Usage

Producer Side (Infrastructure Project)

Simple Alias

Conditional Alias (Pattern-Based)

Simple API

Consumer Side (Application Project)

Deployment Flow

Initial Setup

Keeping Outputs Fresh

CI/CD Orchestration

API Reference

createStackAlias(config)

createConditionalAlias(config)

createSimpleAlias(targetProject, targetStack, outputs)

matchesPattern(pattern, project, stack)

Pattern Format

Comparison with Other Approaches

Benefits

Trade-offs

Use Cases

Shared Development Infrastructure

Ephemeral PR Environments

Multi-Region Deployments

Examples

Migration Guide

From v0.1.0 (Redirect Pattern) to v0.2.0 (Proxy Pattern)

Producer Changes

Consumer Changes

Migration Steps

Contributing

License

Links

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`createStackAlias(config)`

`createConditionalAlias(config)`

`createSimpleAlias(targetProject, targetStack, outputs)`

`matchesPattern(pattern, project, stack)`

Packages