Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 36 ยท Concepts and Stacks

Pulumi Inputs and Outputs: Understanding Output<T>

Learn why Pulumi uses Output values, how inputs flow from one resource to another, what happens during preview, and why you cannot print an Output directly.

The most confusing part of Pulumi for newcomers is Output<T>. It is also the part that makes dependencies automatic. This lesson explains why outputs exist, how to pass them around, and the mistakes that come from treating them like ordinary values.

The problem: values that do not exist yet

When you write const bucket = new aws.s3.BucketV2("assets"), the bucket's id and arn are unknown until AWS creates it. Your program has already moved on to the next line by then. Pulumi solves this with Output values: a wrapper meaning "a value of type T that will be known later (maybe never during a preview)".

TypeScript
const bucket = new aws.s3.BucketV2("assets");

// bucket.id is Output<string>, not string
console.log(bucket.id);          // prints an Output object, NOT the id

Inputs and outputs

Every resource argument accepts an Input, which means either a plain T, a Promise<T> or an Output<T>. Every resource property you read back is an Output. Because inputs accept outputs, you can wire resources together directly:

TypeScript
const bucket = new aws.s3.BucketV2("assets");

const policy = new aws.s3.BucketPolicy("assets-policy", {
  bucket: bucket.id,            // Output<string> passed as an Input<string>
  policy: bucket.arn.apply(arn => JSON.stringify({
    Version: "2012-10-17",
    Statement: [{ Effect: "Allow", Principal: "*", Action: "s3:GetObject", Resource: `${arn}/*` }],
  })),
});

Passing bucket.id records a dependency: the policy depends on the bucket, so Pulumi creates the bucket first. You never write ordering by hand.

apply: use the value when it is known

.apply() takes a function that receives the real value once it is available and returns a new Output:

TypeScript
const url = bucket.bucketDomainName.apply(d => `https://${d}/index.html`);

Rules for apply:

  • The callback may run later, or not at all in a preview if the value is unknown.
  • Do not create resources inside apply unless you must; the engine cannot show them in the preview.
  • The result of apply is again an Output.

Template strings: pulumi.interpolate

String building with several outputs is awkward with apply, so use pulumi.interpolate (a tagged template) or pulumi.concat:

TypeScript
const arnPattern = pulumi.interpolate`${bucket.arn}/*`;

Python: pulumi.Output.concat("https://", bucket.bucket_domain_name) or Output.format("{0}/*", bucket.arn). Go: pulumi.Sprintf("%s/*", bucket.Arn).

Combining several outputs

TypeScript
const summary = pulumi.all([bucket.id, bucket.arn]).apply(([id, arn]) => `${id} -> ${arn}`);

pulumi.all accepts arrays and objects; in newer SDKs pulumi.output({ a, b }) works too.

Why console.log shows nothing useful

TypeScript
console.log(bucket.id);
// Calling [toString] on an Output<T> is not supported.

An Output is a handle, not the string. To log it, use bucket.id.apply(id => console.log(id)), or better, export const bucketId = bucket.id; and read it with pulumi stack output. pulumi.log.info(...) can also take outputs through apply.

Preview versus update

During pulumi preview, outputs of resources that will be created are unknown, and apply callbacks do not run for unknown values (with an exception for isKnown checks). If your callback has side effects or branching on those values, previews and updates may differ. Keep apply callbacks pure: compute, return.

Stand-in: a tiny Output class

This stand-in builds the idea in about twenty lines so you can see why apply exists. It is JavaScript, not the real SDK.

JS Stand-in: a mini Output with apply

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

No output.

Stand-in: automatic dependencies

Passing an output into another resource is what records the dependency. This stand-in tracks which resources an input came from and derives the creation order.

JS Stand-in: dependencies from inputs

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

No output.

The waves show why Pulumi can create the subnet and the security group in parallel: they only share the VPC.

Common mistakes

  1. Concatenating an Output with + gives a nonsense string. Use pulumi.interpolate.
  2. Reading an Output outside apply in an if condition. The value is not known at that point; branch on config instead.
  3. Creating resources inside apply which hides them from previews.
  4. Throwing away dependencies by passing awaited plain values or hard-coded IDs. Pass the Output.
  5. Logging secrets that came out of an apply; the result of an apply on a secret is still secret, but your console.log bypasses that.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is an Output<T>?

    Outputs wrap values that may not be known until the provider has finished.
  2. 2. Passing bucket.id into another resource's argument does what, besides providing the value?

    Dependencies are derived automatically from the outputs used as inputs.
  3. 3. How do you build a string from an Output in TypeScript?

    interpolate (or apply) unwraps the value when it becomes known.
  4. 4. Why should apply callbacks avoid creating resources?

    apply may not run during previews, so resources inside it are invisible to the plan.

Summary

  • Resource properties are Outputs: values that resolve after the provider finishes.
  • Inputs accept plain values or Outputs; using an Output as an input creates a dependency.
  • Use apply, pulumi.interpolate and pulumi.all to work with Output values.
  • You cannot print or concatenate Outputs directly; export them or use apply.
  • Keep apply pure and do not create resources inside it.

Next: Providers and Their Configuration