registerOutputs usage is not clear

[melbourne2991]

I'm a bit confused about the registerOutputs call and what actually is considered an output.
The current documentation says this:

Components can define their own properties using registerOutputs. The Pulumi engine uses this information to display the logical outputs of the component. The call to registerOutputs also tells Pulumi that the resource is done registering children and should be considered fully constructed, so it is recommended that this method be called in all components even if no outputs need to be registered.

That seems to imply that to expose properties you should use registerOutputs. But looking at the source code there are many instances of properties being exposed, yet registerOutputs is called with nothing, or an empty object:

https://github.com/pulumi/pulumi-awsx/blob/88f9bbc90758b08515945d0b93c6cf0a3a24e481/nodejs/awsx/ec2/internetGateway.ts

It seems to me registerOutputs does two things, it signifies that the resource is done being created (as the docs say) and IF you pass something to it and that resource is a top level export Pulumi will only display the registered output properties in the cli/ui.

If passing outputs to it is purely a means of exposing data to the UI/CLI and has no bearing on anything else it may be helpful for the docs to be a bit clearer on that. Maybe rewording it like this (assuming my understanding is correct):

Components can expose properties to the UI and CLI by calling registerOutputs. The call to registerOutputs also tells Pulumi that the resource is done registering children and should be considered fully constructed, so it is recommended that this method be called in all components even if no outputs need to be registered.

[swgillespie]

I'd say - it's not even clear to us what the purpose of registerOutputs is!

At this point, it's basically only a UI gesture. The CLI interprets "registerOutputs" to mean "this resource has completed creation" and transitions the "creating..." text to "created" (and "updating..." to "updated", etc.). It does store the "outputs" in that resource's state, but state for component resources is basically meaningless anyway.

I can't speak for everyone but I think that registerOutputs is a bit of a design wart. We sort-of need it, because this is how stack outputs are implemented, but they don't make any sense at all for component resources other than Stack. @CyrusNajmabadi has taken to passing the empty object to registerOutputs unconditionally because it basically doesn't mean anything.

[CyrusNajmabadi]

@swgillespie Beat me too it. We definitely need to update our docs here. Our current thinking is the following:

1. registerOutputs is needed for ComponentResources primarily as a UI affordance to let code tell the engine "the resource is finished constructing, let the user know that's teh case". It's optional to call, but nice to do. If you miss it you'll just see things like "creating..." in the UI until the program finally finishes. But otherwise, there is no ill effects.
2. We do have a single place in the pulumi stack where we truly call 'registerOutputs' for a resource to expose actual 'output' data. As Sean mentions, it's for the root 'Stack' object, and it's how we actually do things like allow the Stack to report back all the exports of the app module.

By and large, we now think of almost every component resource (except the root 'Stack') as being just an 'aggregation/parenting' concept for other resources. Because they don't actually become a true physical resource in your cloud, and because they don't go through a 'provider' to actually interpret, they don't actually have the concept of either inputs or outputs. As such, we don't even pay attention to inputs on the way in (the base 'ComponentResource' class just ignores them now, and only has htem in the signature for back compat purposes), and we've decided that all-but-one ComponentResource has no outputs, and always just calls .registerOutputs() purely for the UI.

This is def a documentation problem thouhg. I'm going to keep this issue open to track fixing that up. Thanks for the feedback!

[ellismg]

One thing we should keep in mind (and may influence our stance on what sort of outputs to register from a component) is that we expect to do more work around querying an existing deployment by using it's deployment state file. Having components record interesting outputs may make queries easier to write, by allowing components to aggregate some of their child's outputs that are relevant to users of the components.

[icereed]

Is registerOutputs actually needed for dependency tracking of Pulumi?

[boillodmanuel]

Hello,
I came out to the same issue here. :)
In order to understand what is registerOutputs used for, I looked at the source code, and I'm surprised that my call to registerOutputs is totally useless since the (undocumented) initialize method (cf pulumi/pulumi#3676) has appeared, at least for nodejs runtime :-)

Indeed, registerOutputs could be called only once and it has already been called by constructor (cf
https://github.com/pulumi/pulumi/blob/9abcca345a6c024087b35152b0d6fca92baef191/sdk/nodejs/resource.ts#L782-L800).
So, if there is an utility to call registerOutputs, it should be done in initialize method.

Doc to be updated:

• https://www.pulumi.com/docs/intro/concepts/programming-model/#registering-component-outputs
• https://www.pulumi.com/docs/tutorials/aws/s3-folder-component/

[Sytten]

I also came here for the exact same reason, the doc should be updated.