Document dependsOn workarounds for invokes
#12327
Conversation
|
Your site preview for commit f85c9e2 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-12327-f85c9e26.s3-website.us-west-2.amazonaws.com. |
lunaris
force-pushed
the
wjones/depends-on-invokes
branch
from
f85c9e2 to
82374ee
Compare
|
Your site preview for commit 82374ee is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-12327-82374ee2.s3-website.us-west-2.amazonaws.com. |
| @@ -203,18 +356,18 @@ def get_kubeconfig(self, | |||
| <div> | |||
| <pulumi-choosable type="language" values="java"> | |||
|
|
|||
| (no example available for Java) | |||
| No example available for Java | |||
There was a problem hiding this comment.
Are there just no examples in Java and YAML, or are provider methods not supported in those languages? If not supported, is it that they aren't supported yet (in which case it'd also be good to link to an issue), or that they'll never be? (Generally best to be clear on things like this, as folks will likely wonder the same.)
There was a problem hiding this comment.
I'm not actually sure on this -- I've merely (perhaps wrongly) added some cosmetic changes to this bit but am not responsible for the original docs (nor sure on the answers to your questions).
|
|
||
| </pulumi-choosable> | ||
| </div> | ||
|
|
||
| </pulumi-examples></div> | ||
|
|
||
| Unlike provider functions, methods always take `Input` arguments, and return an `Output`. Methods do not have invoke options. | ||
| Unlike provider functions, methods always appear in the _output form_: they take `Input` arguments, and return an `Output`. Moreover, methods do not accept invoke options. |
There was a problem hiding this comment.
Moreover, methods do not accept invoke options.
Just curious -- what does it actually mean that "methods don't accept invoke options"? If "invoke options" are themselves just function arguments, and methods do take arguments, what is this sentence supposed to convey to me as a user? If we deleted it, would anything useful or important be lost?
There was a problem hiding this comment.
So for a "normal" invoke you can do something like aws.getAmi(..., { provider: myCustomProvider }), for instance, where { provider: myCustomProvider } are the invoke options (akin to resource options). Methods don't allow this, (presumably -- again not an expert here) because they'll inherit the options from the resource on which they are being called (so e.g. we don't want to allow you to overload the provider since the owning resource will have already defined one). So at a language level, yes, the method takes arguments, but only those which are inputs to the function, not the "second set" that let you control bits around how Pulumi performs the invoke. If that makes sense? Happy to make changes as you see fit on this.
There was a problem hiding this comment.
Yes, it does make sense, thanks! I didn't realize it was this "second set" that this referred to.
lunaris
force-pushed
the
wjones/depends-on-invokes
branch
from
82374ee to
0b5e542
Compare
|
Your site preview for commit 0b5e542 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-12327-0b5e5423.s3-website.us-west-2.amazonaws.com. |
Invokes, or provider functions, are exposed in many SDKs alongside resources, and allow programs to call arbitrary provider-specific APIs. Just as resources may be passed resource options, so may invokes be passed invoke options, with the usual suspects such as `parent` and `provider` making an appearance and appearing as one might expect. One resource option that is currently not available as an invoke option, despite appearing a natural addition, is `dependsOn`, which allows Pulumi users to make explicit dependencies and ordering constraints in their programs that Pulumi cannot otherwise track. One reason that `dependsOn` does not currently exist as an invoke option is that any given invoke can be called in one of two ways: * A "direct form", whereby the function accepts plain arguments and either blocks until it returns a value or returns a language-native asynchronous value (such as a `Promise` in NodeJS or a `Task` in Python, for instance). * An "output form", whereby the function accepts any Pulumi `Input` values and returns a Pulumi `Output` value. Since direct-form invocations do not use Pulumi `Input`s or `Output`s, they do not form part of the Pulumi dependency graph. Passing `dependsOn` to a direct-form invocation would therefore make no sense. The sharing of the set of invoke options between the two forms means that `dependsOn` is consequently not currently available. Thankfully, one can work around the absence of `dependsOn` for output-form invocations using e.g. `pulumi.all` and `.apply`. This commit updates the documentation on invokes/provider functions to (hopefully) make this clear and provide examples where possible. While we are here we also bolster some of the other pieces of documentation on provider functions, such as defining the terms "direct form" and "output form" which are already referenced on other pages. Fixes pulumi/pulumi#14243
lunaris
force-pushed
the
wjones/depends-on-invokes
branch
from
0b5e542 to
2db1c10
Compare
|
Your site preview for commit 2db1c10 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-12327-2db1c101.s3-website.us-west-2.amazonaws.com. |
Co-authored-by: Christian Nunciato <[email protected]>
|
Your site preview for commit c003456 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-12327-c003456d.s3-website.us-west-2.amazonaws.com. |
Invokes, or provider functions, are exposed in many SDKs alongside resources, and allow programs to call arbitrary provider-specific APIs. Just as resources may be passed resource options, so may invokes be passed invoke options, with the usual suspects such as
parentandprovidermaking an appearance and appearing as one might expect.One resource option that is currently not available as an invoke option, despite appearing a natural addition, is
dependsOn, which allows Pulumi users to make explicit dependencies and ordering constraints in their programs that Pulumi cannot otherwise track. One reason thatdependsOndoes not currently exist as an invoke option is that any given invoke can be called in one of two ways:A "direct form", whereby the function accepts plain arguments and either blocks until it returns a value or returns a language-native asynchronous value (such as a
Promisein NodeJS or aTaskin Python, for instance).An "output form", whereby the function accepts any Pulumi
Inputvalues and returns a PulumiOutputvalue.Since direct-form invocations do not use Pulumi
Inputs orOutputs, they do not form part of the Pulumi dependency graph. PassingdependsOnto a direct-form invocation would therefore make no sense. The sharing of the set of invoke options between the two forms means thatdependsOnis consequently not currently available.Thankfully, one can work around the absence of
dependsOnfor output-form invocations using e.g.pulumi.alland.apply. This commit updates the documentation on invokes/provider functions to (hopefully) make this clear and provide examples where possible. While we are here we also bolster some of the other pieces of documentation on provider functions, such as defining the terms "direct form" and "output form" which are already referenced on other pages.Fixes pulumi/pulumi#14243