Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update invoke docs for dependsOn #13778

Merged
merged 1 commit into from
Jan 9, 2025
+3 −133
Merged

Update invoke docs for dependsOn #13778

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
136 changes: 3 additions & 133 deletions content/docs/iac/concepts/resources/functions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand All @@ -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

Expand Down
Loading