Your organization has a shared infrastructure platform (VPC, EKS, RDS) managed by the platform team, and 20 application teams deploying services into it. How do you use Pulumi stack references to manage cross-stack dependencies safely?
Quick Answer
Use Pulumi StackReference to export outputs from the platform stack (VPC ID, subnet IDs, cluster endpoint) and consume them in application stacks. Enforce contracts via typed interfaces, version outputs, and use Pulumi ESC for environment-level configuration sharing.
Detailed Answer
Architecture Pattern
Structure your Pulumi projects in layers: Layer 0 (networking/VPC), Layer 1 (compute/EKS, databases/RDS), Layer 2 (platform services like ingress, monitoring), Layer 3 (application workloads). Each layer is a separate Pulumi project with its own state, owned by the appropriate team. Upper layers reference lower layers via StackReference, creating a dependency graph without tight coupling.
Stack Reference Mechanics
The platform team exports outputs from their stack using pulumi.export(). Application teams consume these using new pulumi.StackReference('org/infra/prod') and call getOutput('vpcId'). Critically, stack references return Output<T> values that are resolved asynchronously during deployment, maintaining Pulumi's dependency tracking. If the referenced stack's output changes, dependent stacks see the new value on their next deployment.
Contract Enforcement
The danger with cross-stack references is breaking changes: the platform team renames an output and 20 application stacks break. Mitigate this by defining a typed interface for stack outputs, versioning the contract, and running integration tests that verify outputs exist before merging platform changes. In TypeScript, create a shared npm package defining the output interface that both platform and application code import.
Operational Concerns
Stack references create implicit deployment ordering. The platform stack must be deployed before application stacks. Implement this in CI/CD with explicit pipeline stages. Use pulumi preview in application stacks after platform changes to detect breakage before applying. Consider using Pulumi ESC (Environments, Secrets, Configuration) as a higher-level abstraction for sharing environment configuration that doesn't require direct stack-to-stack references.