diff --git a/content/docs/iac/concepts/resources/functions.md b/content/docs/iac/concepts/resources/functions.md index ec51b9af4120..6780ca777cef 100644 --- a/content/docs/iac/concepts/resources/functions.md +++ b/content/docs/iac/concepts/resources/functions.md @@ -145,6 +145,8 @@ The [Pulumi Registry](/registry) contains authoritative documentation for all pr Functions also accept "invoke options", similar to the way Pulumi resources accept [resource options](/docs/concepts/options/). Invoke options may be specified either as an object or as a list of arguments depending on the language you're writing your Pulumi program in. The options are as follows: +- `dependsOn`: An array of resources that this function depends on, see [Dependencies and ordering](#dependencies-and-ordering). This option is only available on Output form invocations. + - `parent`: Supply a parent resource for this function call. Much like the [parent resource option](/docs/concepts/options/parent/), the parent will be consulted when determining the provider to use. - `pluginDownloadURL`: Pass a URL from which the provider plugin should be fetched. This may be necessary for third-party packages such as those not hosted at [https://get.pulumi.com](https://get.pulumi.com). @@ -163,139 +165,7 @@ While the direct and output forms of a provider function are equivalent in terms - Output form invocations, on the other hand, are tracked by the Pulumi engine and participate in the dependency graph. This means, for example, that Pulumi will ensure that input resources are created or updated before an invocation and that the invocation is executed before its dependent resources are created or updated. -If you require that dependent resources are created or updated before an invocation, you must use a provider function's output form. If you need to specify a dependency that can't be captured by passing an appropriate input (that is, if you wish to simulate something like the [`dependsOn` resource option](/docs/concepts/options/dependson/)), you can use Pulumi's [`all`](/docs/concepts/inputs-outputs/all/) function and `Output`'s [`apply`](/docs/concepts/inputs-outputs/apply/) method: - -{{< chooser language "typescript,python,go,csharp,java,yaml" >}} -{{% choosable language typescript %}} - - ```typescript -import * as pulumi from "@pulumi/pulumi"; - -const res1 = new MyResource("res1", {}); -const res2 = new MyResource("res2", {}); - -// Assuming `myFunctionOutput` is an output-form invocation of the `myFunction` -// provider function, this use of `all` and `apply` will ensure that it does not -// happen until `res1` and `res2` have been processed. This will work for any -// set of resources, even those with no explicit outputs, since the `.urn` -// output is always available. -pulumi.all([res1.urn, res2.urn]).apply(() => myFunctionOutput()); -``` - -{{% /choosable %}} -{{% choosable language csharp %}} - -```csharp -using System.Collections.Generic; -using System.Linq; -using Pulumi; - -return await Deployment.RunAsync(() => -{ - var res1 = new MyResource("res1", new MyResourceArgs()); - var res2 = new MyResource("res2", new MyResourceArgs()); - - // Assuming `myFunctionOutput` is an output-form invocation of the `myFunction` - // provider function, this use of `Tuple` and `Apply` will ensure that it does - // not happen until `res1` and `res2` have been processed. This will work for - // any set of resources, even those with no explicit outputs, since the `.Urn` - // output is always available. - Output.Tuple(res1.Urn, res2.Urn).Apply(t => myFunctionOutput()); -}); -``` - -{{% /choosable %}} -{{% choosable language go %}} - -```go -package main - -import ( - "github.com/pulumi/pulumi/sdk/v3/go/pulumi" -) - -func main() { - pulumi.Run(func(ctx *pulumi.Context) error { - res1, err := NewMyResource(ctx, "res1", nil) - if err != nil { - return err - } - - res2, err := NewMyResource(ctx, "res2", nil) - if err != nil { - return err - } - - // Assuming `myFunctionOutput` is an output-form invocation of the `myFunction` - // provider function, this use of `All` and `ApplyT` will ensure that it does not - // happen until `res1` and `res2` have been processed. This will work for any set - // of resources, even those with no explicit outputs, since the `.URN` output is - // always available. - _, err = pulumi.All(res1.URN, res2.URN).ApplyT(func(args []interface{}) (interface{}, error) { - return myFunctionOutput() - }) - if err != nil { - return err - } - - return nil - }) -} -``` - -{{% /choosable %}} -{{% choosable language python %}} - -```python -import pulumi - -res1 = MyResource("res1", {}) -res2 = MyResource("res2", {}) - -# Assuming `my_function_output` is an output-form invocation of the `my_function` -# provider function, this use of `all` and `apply` will ensure that it does not -# happen until `res1` and `res2` have been processed. This will work for any set -# of resources, even those with no explicit outputs, since the `.urn` output is -# always available. -pulumi.all(res1.urn, res2.urn).apply(lambda args: my_function_output()) -``` - -{{% /choosable %}} -{{% choosable language java %}} - -```java -package generated_program; - -import com.pulumi.Context; -import com.pulumi.Output; -import com.pulumi.Pulumi; - -public class App { - public static void main(String[] args) { - Pulumi.run(App::stack); - } - - public static void stack(Context ctx) { - final var res1 = new MyResource("res1", new MyResourceArgs()); - final var res2 = new MyResource("res2", new MyResourceArgs()); - - // Assuming `myFunctionOutput` is an output-form invocation of the `myFunction` - // provider function, this use of `tuple` and `applyValue` will ensure that it does - // not happen until `res1` and `res2` have been processed. This will work for - // any set of resources, even those with no explicit outputs, since the `.urn` - // output is always available. - Output.tuple(res1.getUrn(), res2.getUrn()).applyValue(t -> myFunctionOutput()); - } -} -``` - -{{% /choosable %}} -{{% choosable language yaml %}} - -Output form invocations are not yet supported in YAML. - -{{% /choosable %}} -{{< /chooser >}} +If you require that dependent resources are created or updated before an invocation, you must use a provider function's output form. If you need to specify a dependency that can't be captured by passing an appropriate input, you can use the `dependsOn` option to specify additional dependencies. ### Resource methods