Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 36 ยท Concepts and Stacks

Pulumi Stack Outputs and Stack References

Export values from a Pulumi stack, read them with the CLI, and share them between projects with StackReference. Includes secrets in outputs and layering network, data and app stacks.

A stack's outputs are the values it publishes: a URL, a database endpoint, a VPC ID, a kubeconfig. People and scripts read them with the CLI, and other stacks read them with a StackReference. This is how you split infrastructure into layers without copying IDs by hand.

Exporting values

At the end of your program, export what others need:

TypeScript
export const bucketName = bucket.id;
export const websiteUrl = pulumi.interpolate`http://${bucket.websiteEndpoint}`;
export const settings = { region: "eu-west-1", versioning: true };
Python
pulumi.export("bucket_name", bucket.id)
pulumi.export("settings", {"region": "eu-west-1", "versioning": True})

Outputs can be strings, numbers, booleans, lists or objects. They are recorded in the state after each successful update.

Reading outputs from the CLI

Terminal
pulumi stack output                      # table of all outputs
pulumi stack output bucketName           # one output, raw
pulumi stack output settings --json      # JSON, handy with jq
pulumi stack output --show-secrets       # reveal secret outputs

Scripts often use this to pass a value to the next tool:

Terminal
BUCKET=$(pulumi stack output bucketName)
aws s3 sync ./site "s3://$BUCKET"

Secret outputs

If an output is derived from a secret, Pulumi keeps it encrypted in state and prints [secret] instead of its value. You can mark one yourself:

TypeScript
export const dbPassword = pulumi.secret(generatedPassword);

Use --show-secrets only when you must. See Secrets in Config for how secrets are protected.

StackReference: reading another stack

A StackReference gives a program access to the outputs of a different stack, even in another project.

TypeScript
import * as pulumi from "@pulumi/pulumi";

const network = new pulumi.StackReference("acme/network/prod");

const vpcId = network.getOutput("vpcId");                 // Output<any>
const subnetIds = network.requireOutput("privateSubnetIds");

const instance = new aws.ec2.Instance("app", {
  subnetId: subnetIds.apply(ids => ids[0]),
  vpcSecurityGroupIds: [],
  ami: "ami-0abcdef1234567890",
  instanceType: "t3.small",
});

The name is the fully qualified stack name, organization/project/stack (Stacks and Projects). getOutput returns an unknown Output if the name does not exist; requireOutput fails the update with an error, which is usually what you want. In a common idiom the reference name depends on the current stack:

TypeScript
const env = pulumi.getStack();                       // "dev" or "prod"
const network = new pulumi.StackReference(`acme/network/${env}`);

The consuming program does not create dependencies on the other stack's resources; it only reads recorded values. Deploy order is your responsibility: update network first, then app. If the network stack later changes an output, the app stack sees the new value on its next pulumi up.

Layered architecture

flowchart LR
  N["network stack<br/>exports vpcId, subnets"] --> D["data stack<br/>exports dbEndpoint"]
  N --> A["app stack"]
  D --> A

Arrows show which stacks read outputs from which.

Advantages: each layer has its own blast radius, permissions and release rhythm; the network team and the application team do not block each other. Costs: more projects to deploy, a defined order, and a contract (the output names) that you must treat like an API. Renaming an output breaks consumers.

Alternatives to StackReference

  • Configuration: for slow-moving values, copy them into config. Simple, but they can go stale.
  • Pulumi ESC: environments publish values to many stacks (ESC Environments).
  • Pulumi Deployments or Automation API: orchestrate several stacks in one program.
  • Single project, components: if two things always change together, keep them in one stack.

Stand-in: stacks sharing outputs

This stand-in models stacks as objects with outputs and a reference function, including the difference between get and require.

JS Stand-in: StackReference

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

No output.

Stand-in: stale values and deploy order

JS Stand-in: the consumer sees old values until it redeploys

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. Which command prints a single stack output as plain text?

    pulumi stack output <name> reads it from the stack's state.
  2. 2. What does a StackReference give you?

    It reads outputs only; it does not create dependencies or change the other stack.
  3. 3. Which method fails the update when an output does not exist?

    requireOutput raises an error; getOutput returns an unknown value.
  4. 4. You change an output in the network stack. When does the app stack see it?

    The reference is read when the consumer's program runs.

Summary

  • export publishes values; pulumi stack output reads them (use --json for scripts).
  • Secret-derived outputs stay encrypted and display as [secret].
  • StackReference("org/project/stack") reads another stack's outputs; prefer requireOutput.
  • Layer stacks (network, data, app) and treat output names as a stable contract.
  • Deploy order across stacks is your responsibility.

Next: Resource Options: dependsOn, protect, aliases and more