Link registry docs to example for CFN Custom Resource (#1817)

This change adds a Readme for the CFN Custom Resource example and links
it in the registry docs.

examples/cfn-custom-resource/README.md

@@ -0,0 +1,41 @@
+# AWS CloudFormation Custom Resource Emulator
+
+This example demonstrates how to use AWS CloudFormation Custom Resources directly in your Pulumi programs using the Custom Resource Emulator. It shows how to invoke AWS Lambda functions that implement custom provisioning logic following the CloudFormation Custom Resource protocol.
+
+## Overview
+
+The Custom Resource Emulator allows you to seamlessly integrate existing CloudFormation Custom Resources into your Pulumi infrastructure code. This example illustrates the conversion of a CloudFormation Custom Resource implementation to its Pulumi equivalent, highlighting the similarities and differences between both approaches.
+
+> **Note**: Currently, only Lambda-backed Custom Resources are supported. SNS-backed Custom Resources are not supported at this time.
+
+## Components
+
+The example consists of two main parts:
+
+1. **Lambda Function**: A simple AWS Lambda function that implements the Custom Resource protocol to retrieve EC2 AMIs.
+2. **Custom Resource**: The Pulumi resource that invokes the Lambda function using the Custom Resource Emulator.
+
+## Code Structure
+
+```
+.
+├── index.ts                # Pulumi program
+├── ami-lookup.js           # The Lambda Function Code
+├── Pulumi.yaml             # Pulumi project file
+└── package.json            # Node.js package file
+```
+
+## Implementation Details
+
+The example demonstrates:
+- How to create a Lambda function that implements the Custom Resource protocol
+- How to use the Custom Resource Emulator to invoke the Lambda function
+- How to pass properties to the Custom Resource
+- How to retrieve outputs from the Custom Resource
+
+
+## Additional Resources
+
+- [Pulumi AWS Native Provider Documentation](https://www.pulumi.com/docs/reference/pkg/aws-native/)
+- [CloudFormation Custom Resource Documentation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-custom-resources.html)
+- [Custom Resource Protocol Specification](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/crpg-ref.html)

provider/cmd/pulumi-resource-aws-native/schema.json

@@ -181222,7 +181222,7 @@
             ]
         },
         "aws-native:cloudformation:CustomResourceEmulator": {
-            "description": "The Custom Resource Emulator allows you to use AWS CloudFormation Custom Resources directly in your Pulumi programs. It provides a way to invoke AWS Lambda functions that implement custom provisioning logic following the CloudFormation Custom Resource protocol.\n\n\u003e **Note**: Currently, only Lambda-backed Custom Resources are supported. SNS-backed Custom Resources are not supported at this time.\n\n## Example Usage\n\n```typescript\nimport * as aws from \"@pulumi/aws-native\";\n\nconst bucket = new aws.s3.Bucket('custom-resource-emulator');\n\n// Create a Custom Resource that invokes a Lambda function\nconst cr = new aws.cloudformation.CustomResourceEmulator('cr', {\n    bucketName: bucket.id,\n    bucketKeyPrefix: 'custom-resource-emulator',\n    customResourceProperties: {\n        hello: \"world\"\n    },\n    serviceToken: \"arn:aws:lambda:us-west-2:123456789012:function:my-custom-resource\",\n    resourceType: 'Custom::MyResource',\n}, { customTimeouts: { create: '5m', update: '5m', delete: '5m' } });\n\n// Access the response data\nexport const customResourceData = customResource.data;\n```\n\n## About CloudFormation Custom Resources\n\nCloudFormation Custom Resources allow you to write custom provisioning logic for resources that aren't directly available as AWS CloudFormation resource types. Common use cases include:\n\n- Implementing complex provisioning logic\n- Performing custom validations or transformations\n- Integrating with third-party services\n- Implementing organization-specific infrastructure patterns\n\nFor more information about CloudFormation Custom Resources, see [Custom Resources](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-custom-resources.html) in the AWS CloudFormation User Guide.\n\n## Permissions\n\nThe IAM principal used by your Pulumi program must have the following permissions:\n\n1. `lambda:InvokeFunction` on the Lambda function specified in `serviceToken`\n2. S3 permissions on the bucket specified in `bucketName`:\n   - `s3:PutObject`\n   - `s3:GetObject`\n   - `s3:HeadObject`\n\n## Lambda Function Requirements\n\nThe Lambda function specified in `serviceToken` must implement the CloudFormation Custom Resource lifecycle.\nFor detailed information about implementing Lambda-backed Custom Resources, see [AWS Lambda-backed Custom Resources](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-custom-resources-lambda.html) in the AWS CloudFormation User Guide.\n\n## Timeouts\n\nCustom Resources have a default timeout of 60 minutes, matching the CloudFormation timeout for custom resource operations. You can customize it using the [`customTimeouts`](https://www.pulumi.com/docs/iac/concepts/options/customtimeouts/) resource option.\n",
+            "description": "The Custom Resource Emulator allows you to use AWS CloudFormation Custom Resources directly in your Pulumi programs. It provides a way to invoke AWS Lambda functions that implement custom provisioning logic following the CloudFormation Custom Resource protocol.\n\n\u003e **Note**: Currently, only Lambda-backed Custom Resources are supported. SNS-backed Custom Resources are not supported at this time.\n\n## Example Usage\n\n```typescript\nimport * as aws from \"@pulumi/aws-native\";\n\nconst bucket = new aws.s3.Bucket('custom-resource-emulator');\n\n// Create a Custom Resource that invokes a Lambda function\nconst cr = new aws.cloudformation.CustomResourceEmulator('cr', {\n    bucketName: bucket.id,\n    bucketKeyPrefix: 'custom-resource-emulator',\n    customResourceProperties: {\n        hello: \"world\"\n    },\n    serviceToken: \"arn:aws:lambda:us-west-2:123456789012:function:my-custom-resource\",\n    resourceType: 'Custom::MyResource',\n}, { customTimeouts: { create: '5m', update: '5m', delete: '5m' } });\n\n// Access the response data\nexport const customResourceData = customResource.data;\n```\n\nA full example of creating a CloudFormation Custom Resource Lambda function and using it in Pulumi can be found [here](https://github.com/pulumi/pulumi-aws-native/tree/master/examples/cfn-custom-resource).\n\n## About CloudFormation Custom Resources\n\nCloudFormation Custom Resources allow you to write custom provisioning logic for resources that aren't directly available as AWS CloudFormation resource types. Common use cases include:\n\n- Implementing complex provisioning logic\n- Performing custom validations or transformations\n- Integrating with third-party services\n- Implementing organization-specific infrastructure patterns\n\nFor more information about CloudFormation Custom Resources, see [Custom Resources](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-custom-resources.html) in the AWS CloudFormation User Guide.\n\n## Permissions\n\nThe IAM principal used by your Pulumi program must have the following permissions:\n\n1. `lambda:InvokeFunction` on the Lambda function specified in `serviceToken`\n2. S3 permissions on the bucket specified in `bucketName`:\n   - `s3:PutObject`\n   - `s3:GetObject`\n   - `s3:HeadObject`\n\n## Lambda Function Requirements\n\nThe Lambda function specified in `serviceToken` must implement the CloudFormation Custom Resource lifecycle.\nFor detailed information about implementing Lambda-backed Custom Resources, see [AWS Lambda-backed Custom Resources](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-custom-resources-lambda.html) in the AWS CloudFormation User Guide.\n\n## Timeouts\n\nCustom Resources have a default timeout of 60 minutes, matching the CloudFormation timeout for custom resource operations. You can customize it using the [`customTimeouts`](https://www.pulumi.com/docs/iac/concepts/options/customtimeouts/) resource option.\n",
             "properties": {
                 "bucket": {
                     "type": "string",

provider/pkg/schema/docs/content/cfn-custom-resource.md

@@ -24,6 +24,8 @@ const cr = new aws.cloudformation.CustomResourceEmulator('cr', {
 export const customResourceData = customResource.data;
 ```
 
+A full example of creating a CloudFormation Custom Resource Lambda function and using it in Pulumi can be found [here](https://github.com/pulumi/pulumi-aws-native/tree/master/examples/cfn-custom-resource).
+
 ## About CloudFormation Custom Resources
 
 CloudFormation Custom Resources allow you to write custom provisioning logic for resources that aren't directly available as AWS CloudFormation resource types. Common use cases include: