Pulumi Stack References Guide – Share Outputs Between Stacks

Learn how to expose a value from one Pulumi stack and consume it in another using Stack References, with step‑by‑step commands, verification steps, and rollback guidance.

Desired outcome

Expose a value (e.g., a database connection string) from an infrastructure stack so that an application stack can consume it without hard‑coding secrets.

Prerequisites

Pulumi CLI installed (version 3.0 or later).
Access to a supported backend (Pulumi Service, self‑managed, or AWS S3) with the same organization for both stacks.
Two existing Pulumi stacks configured with TypeScript: an infrastructure stack (infra) and an application stack (app).
Cloud provider credentials (e.g., AWS) configured for the resources you will create.
Appropriate IAM permissions to read stack outputs and to create/update resources in both stacks.

Procedure

Export the value from the infrastructure stack

In the infra stack directory, edit index.ts (or the file where you define resources) to return the desired output:

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

const db = new aws.rds.Instance("mydb", {
    instanceClass: "db.t3.micro",
    engine: "mysql",
    allocatedStorage: 20,
    username: "admin",
    password: "SuperSecret123!",
});

export const connectionString = db.address.apply(addr => 
    `mysql://admin:SuperSecret123!@${addr}:3306/mydb`);

return { connectionString };

Run pulumi up in the infra stack to provision the RDS instance and store the output.

Reference the output in the application stack

In the app stack directory, import the infrastructure stack using a StackReference and retrieve the output:

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

const infraRef = new pulumi.StackReference("/infra/prod");
const connectionString = infraRef.getOutput("connectionString");

// Example: pass the connection string to a Lambda environment variable
const lambda = new aws.lambda.Function("processor", {
    runtime: "nodejs18.x",
    handler: "index.handler",
    code: new pulumi.asset.AssetArchive({
        ".": new pulumi.asset.FileArchive("./lambda")
    }),
    environment: {
        variables: {
            DB_CONNECTION_STRING: connectionString
        }
    }
});

export const lambdaArn = lambda.arn;

Replace with your Pulumi organization name and infra/prod with the stack name you want to reference.

Preview and apply changes
From the app stack directory, run:
```
pulumi preview
```
Check the preview output for a line similar to:
```
    connectionString = 
```
If the value appears correctly, proceed with:
```
pulumi up
```

Expected checks

Verify the infra stack output exists:

# in the infra stack directory
pulumi stack output connectionString

Confirm the referenced value in the app stack preview:

# in the app stack directory
pulumi up --preview

Look for the exported value in the preview table under Outputs.

After a successful pulumi up, deploy a test resource (e.g., an AWS Lambda) that logs the connection string and inspect the logs:

# Example Lambda handler (Node.js)
exports.handler = async () => {
    console.log("DB connection string:", process.env.DB_CONNECTION_STRING);
    return { statusCode: 200 };
};

Check CloudWatch Logs for the Lambda to ensure the logged string matches the expected format.

Rollback / recovery options

Since pulumi up modifies state, you can revert changes:

Run pulumi destroy in the app stack to remove the Lambda and any resources that used the referenced output.
If you need to revert to a previous revision, use pulumi stack history to list revisions and pulumi stack select followed by pulumi up --target to re‑apply a specific version.
Always keep the infrastructure stack unchanged unless you intentionally update the exported value; changing the infra stack will automatically update referencing stacks on their next pulumi up.

Limitations and practical verification

Both stacks must use the same backend and organization; referencing across different backends or organizations will fail with an authentication error.
Avoid circular references: do not export a value from the app stack that the infra stack depends on, as Pulumi will reject the dependency loop.
To verify that the StackReference is correctly configured, run pulumi stack output on the infra stack and compare the value with what appears in the app stack preview.

Sharing Infrastructure Outputs with Pulumi Stack References in TypeScript