Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 36 ยท Components and Reuse

Designing Component Inputs and Outputs: Input, Output and apply

Design clean Pulumi component APIs: Input and Output types, defaults, secrets, apply and interpolate, avoiding unknown-value traps and exposing only what callers need.

A component is an API. Callers pass inputs, read outputs and never look at the resources inside. Good API design decides whether your component is pleasant for years or a source of constant breaking changes. In Pulumi the main design question is how to handle Input and Output types, because values often are not known until the cloud has created something.

Pulumi itself cannot run on this site, so TypeScript examples are read-only and the runnable code is a small JavaScript stand-in of the Output idea (a value that may arrive later, and a way to transform it).

Input and Output in one minute

  • pulumi.Output<T> is a value that may be unknown during pulumi preview and becomes known after a resource is created, for example a bucket ARN.
  • pulumi.Input<T> is "a plain T, a promise of T or an Output<T>". Resource arguments accept Input<T>, so you can pass either literals or outputs of other resources.

For component arguments, declare properties as Input<T> so callers can wire resources together without unwrapping:

TypeScript
export interface ApiArgs {
  vpcId: pulumi.Input<string>;
  subnetIds: pulumi.Input<string>[];
  instanceCount?: pulumi.Input<number>;
  tags?: pulumi.Input<Record<string, pulumi.Input<string>>>;
}

Declare component outputs as pulumi.Output<T> fields (usually public readonly).

Transforming outputs with apply and interpolate

You cannot use an Output<string> as a string. bucket.bucket + "/logs" gives nonsense, because the value is not there yet. Use:

  • output.apply(v => ...) to compute a new output from the resolved value.
  • pulumi.interpolate, a tagged template, for strings (see the example below).
  • pulumi.all([a, b]).apply(([x, y]) => ...) to combine several outputs.
  • pulumi.concat(...) for simple concatenation, and pulumi.jsonStringify for JSON policies that embed outputs.
TypeScript
const url = bucket.bucket.apply(name => `https://${name}.s3.amazonaws.com`);
const same = pulumi.interpolate`https://${bucket.bucket}.s3.amazonaws.com`;
const both = pulumi.all([bucket.arn, role.arn]).apply(([b, r]) => `${r} can read ${b}`);

Two rules keep you out of trouble:

  1. Never create resources inside apply unless you must. During preview the callback may not run, so the resources would be invisible in the plan.
  2. Do not console.log an output expecting a value. Use pulumi.log.info inside apply, or export the value and read it with pulumi stack output.

A stand-in for Output

This is not the Pulumi SDK. It models a value with a "known or unknown" state, so you can see why apply exists and why preview prints [unknown].

Node.js Stand-in: a tiny Output with apply and all

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice the preview line: anything derived from an unknown value is also unknown. That is why if (bucket.arn.apply(...)) style conditionals do not work: you cannot branch on a value that does not exist yet. Branch on inputs and config (known at preview), not on outputs.

Secrets travel with values

If a component receives a secret (a database password), keep it an Output and pass it through. Pulumi marks any output derived from a secret as secret too, and encrypts it in state. Do not unwrap it into a plain string, and never put it in a resource name or a tag.

TypeScript
const password = config.requireSecret("dbPassword");     // Output<string>, secret
const db = new aws.rds.Instance(`${name}-db`, { password, /* ... */ }, { parent: this });
// To be extra careful about outputs you return:
pulumi.secret(connectionString);

You can also force parts of your outputs to be secret with additionalSecretOutputs on a resource, for example for a generated key the provider returns in plain text.

Defaults, validation and a stable surface

Practical guidelines for component APIs:

  • Provide defaults for everything except identity. name is required; retentionDays defaults to 30.
  • Use unions of string literals ("dev" | "staging" | "prod") instead of free text.
  • Validate on known values early. For inputs that may be outputs, validate in an apply, or document the constraint.
  • Prefer a flat args object over positional parameters. Adding a property later is not a breaking change.
  • Return identifiers, not resources. Return bucketName and arn, not the entire Bucket object. Callers cannot depend on your internals, so you can swap them.
  • Name things after the domain, not the provider: databaseUrl, not rdsInstanceEndpointAddress.

The next stand-in applies these ideas: defaults merged with caller inputs, validation, and a frozen result that only exposes public outputs.

Node.js Stand-in: args with defaults, validation and a small public surface

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Common mistakes

  • Typing arguments as string instead of pulumi.Input<string>, which forces callers to unwrap outputs.
  • Using apply to build strings when pulumi.interpolate is clearer.
  • Creating resources inside apply, so previews hide them.
  • Returning the internal resource objects and later being unable to change them.
  • Printing secrets via console.log or apply into logs.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why should component argument properties be typed pulumi.Input<T> rather than plain T?

    Input<T> accepts a plain value, a promise or an Output<T>, which lets callers wire resources together directly.
  2. 2. What does pulumi.interpolate do?

    pulumi.interpolate is a tagged template that combines plain text and outputs into a new output string.
  3. 3. Which is the best thing to branch on when deciding whether to create a resource?

    Outputs can be unknown during preview, so the plan would be incomplete. Config values and plain inputs are known up front.
  4. 4. A component returns its whole internal Bucket object as an output. What is the risk?

    Expose stable identifiers such as names and ARNs instead of internal resource objects so the implementation can change.

Summary

  • Component arguments use Input<T>; component outputs are Output<T>.
  • Transform outputs with apply, interpolate, all and concat; do not create resources inside apply.
  • Anything derived from an unknown value is unknown in preview; branch on config and plain inputs.
  • Keep secrets as outputs and never print them.
  • Offer defaults, validate early, use a flat args object and return identifiers, not internals.

Next: Pulumi Packages and Multi-Language Components