You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Restructure Functions documentation as top-level concept
- Create new Functions overview page explaining three function types
- Move provider functions from resources section to functions section
- Move get functions from resources section to functions section
- Extract resource methods into separate page
- Remove JavaScript example from get functions page
- Update navigation structure and menu weights
Addresses GitHub issue #15438 by elevating Functions from a sub-page
of Resources to a top-level concept in the documentation.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Pulumi provides three types of functions that you can use in your programs to interact with cloud resources and retrieve data from cloud providers. Understanding these different function types and when to use them is essential for writing effective Pulumi programs.
20
+
21
+
## Provider functions
22
+
23
+
**[Provider functions](/docs/iac/concepts/functions/provider-functions/)** are functions exposed in Pulumi providers that allow you to query cloud APIs to retrieve data that is not part of a resource. These functions are often used to look up information about existing cloud resources that you need in your Pulumi program.
24
+
25
+
For example, you might use a provider function to get the latest virtual machine image ID for a specific operating system.
26
+
27
+
## Get functions
28
+
29
+
**[Get functions](/docs/iac/concepts/functions/get-functions/)** are static functions available on all Pulumi resource types that allow you to reference an existing resource that is not managed by Pulumi. Unlike the `pulumi import` command which brings resources under Pulumi management, get functions simply allow you to read the properties of existing resources.
30
+
31
+
Get functions are useful when you know an unmanaged resource's identity and need to reference properties of the unmanaged resource in resources that _are_ managed by Pulumi.
32
+
33
+
For example, you might want to get a virtual network by ID and use its CIDR block in a firewall rule.
34
+
35
+
Resources accessed via get functions will never be updated or deleted by Pulumi.
36
+
37
+
## Resource methods
38
+
39
+
**[Resource methods](/docs/iac/concepts/functions/resource-methods/)** are functions attached to specific resource types that return computed values from resources you are managing with Pulumi. These methods are called on resource instances and typically provide additional derived information about that resource.
40
+
41
+
For example, some managed Kubernetes cluster resources have a resource method to return the generate Kubeconfig file.
42
+
43
+
## Choosing the right function type
44
+
45
+
- Use **provider functions** when you need to query cloud provider APIs for data or configuration
46
+
- Use **get functions** when you need to reference existing resources that aren't managed by Pulumi
47
+
- Use **resource methods** when you need to get computed values from resources you're managing with Pulumi
48
+
49
+
Understanding these distinctions will help you write more effective Pulumi programs.
@@ -26,23 +27,8 @@ Two values are passed to the `get` function:
26
27
27
28
You can use the `get` function to consume properties from a resource that was provisioned elsewhere. For example, this program reads an existing EC2 Security Group whose ID is `sg-0dfd33cdac25b1ec9` and uses the result as input to create an EC2 Instance that Pulumi will manage:
28
29
29
-
{{< chooser language "javascript,typescript,python,go,csharp,java,yaml" >}}
30
+
{{< chooser language "typescript,python,go,csharp,java,yaml" >}}
30
31
31
-
{{% choosable language javascript %}}
32
-
33
-
```javascript
34
-
let aws =require("@pulumi/aws");
35
-
36
-
let group =aws.ec2.SecurityGroup.get("group", "sg-0dfd33cdac25b1ec9");
37
-
38
-
let server =newaws.ec2.Instance("web-server", {
39
-
ami:"ami-6869aa05",
40
-
instanceType:"t2.micro",
41
-
securityGroups: [ group.name ], // reference the security group resource above
@@ -263,7 +264,7 @@ While the direct and output forms of a provider function will both return the sa
263
264
264
265
## Choosing between direct form and output form
265
266
266
-
There are several common scenarios where one form or the other _must_ be used:
267
+
There are several common scenarios where either direct form or output form must or should be used:
267
268
268
269
* **If you need a provider function's result to determine whether a resource should be created at all**, you must use the provider function's the direct form. The direct form of a function executes _while_ the Pulumi engine is formulating the dependency graph (that is, determining what resources need to be created, updated, or deleted), so in order to figure out whether a resource belongs in the graph at all, that decision has to always be calculated up front.
269
270
* **If you need resources to be created or updated before the function is invoked**, you should use the provider function's output form. (It is _possible_ to use the direct form in this case, but it requires wrapping the call in an `apply`, which can be awkward from a readability standpoint.) Dependencies in the output form of a function are tracked identically to resources: all inputs to the function must be resolved before the function executes. If you need to specify a dependency that isn't already implied by an input to the function's arguments, you can use the `dependsOn` function option to specify additional dependencies (just like you can with resources).
@@ -276,66 +277,3 @@ Pulumi recommends you choose the output form of a function unless you have a spe
276
277
277
278
Assuming there is no specific reason to choose one or the other, the choice between the two forms is ultimately a preference: there is no significant difference in either performance or code maintainability between the two forms.
278
279
{{% / notes %}}
279
-
280
-
## Resource methods
281
-
282
-
Provider SDKs may also include _methods_ attached to a resource type. For example, in the [EKS](/registry/packages/eks/api-docs/) SDK, the `Cluster` resource has a [.GetKubeconfig](/registry/packages/eks/api-docs/cluster/#method_GetKubeconfig) method:
Unlike provider functions, methods always appear in the _output form_: they take `Input` arguments, and return an `Output` (because they cannot execute until after the resources has been created). Moreover, methods do not accept invoke options.
meta_desc: Learn about resource methods - functions attached to resource types that return computed values from resources you are managing with Pulumi.
Provider SDKs may also include _methods_ attached to a resource type. These methods return computed values from resources you are managing with Pulumi. For example, in the [EKS](/registry/packages/eks/api-docs/) SDK, the `Cluster` resource has a [.GetKubeconfig](/registry/packages/eks/api-docs/cluster/#method_GetKubeconfig) method:
Unlike provider functions, methods always appear in the _output form_: they take `Input` arguments, and return an `Output` (because they cannot execute until after the resource has been created). Resource methods do not accept invoke options.
0 commit comments