Skip to content

Commit

Permalink
Add docs for custom resource
Browse files Browse the repository at this point in the history
  • Loading branch information
flostadler committed Nov 8, 2024
1 parent 5d213df commit e46c00a
Show file tree
Hide file tree
Showing 4 changed files with 71 additions and 3 deletions.
4 changes: 2 additions & 2 deletions provider/pkg/resources/cfn_custom_resource.go
Original file line number Diff line number Diff line change
Expand Up @@ -139,10 +139,10 @@ func (s CfnCustomResourceState) ToPropertyMap() resource.PropertyMap {
return resource.NewPropertyMap(s)
}

func CfnCustomResourceSpec() pschema.ResourceSpec {
func CfnCustomResourceSpec(description string) pschema.ResourceSpec {
return pschema.ResourceSpec{
ObjectTypeSpec: pschema.ObjectTypeSpec{
Description: "TODO: pulumi/pulumi-cdk#109",
Description: description,
Properties: map[string]pschema.PropertySpec{
"physicalResourceId": {
Description: "The name or unique identifier that corresponds to the `PhysicalResourceId` included in the Custom Resource response. If no `PhysicalResourceId` is provided in the response, a random ID will be generated.",
Expand Down
56 changes: 56 additions & 0 deletions provider/pkg/schema/docs/content/cfn-custom-resource.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
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.

> **Note**: Currently, only Lambda-backed Custom Resources are supported. SNS-backed Custom Resources are not supported at this time.
## Example Usage

```typescript
import * as aws from "@pulumi/aws-native";

const bucket = new aws.s3.Bucket('custom-resource-emulator');

// Create a Custom Resource that invokes a Lambda function
const cr = new aws.cloudformation.CustomResourceEmulator('cr', {
bucketName: bucket.id,
bucketKeyPrefix: 'custom-resource-emulator',
customResourceProperties: {
hello: "world"
},
serviceToken: "arn:aws:lambda:us-west-2:123456789012:function:my-custom-resource",
resourceType: 'Custom::MyResource',
}, { customTimeouts: { create: '5m', update: '5m', delete: '5m' } });

// Access the response data
export const customResourceData = customResource.data;
```

## 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:

- Managing resources outside of AWS (e.g., GitHub repositories, external APIs)
- Implementing complex provisioning logic
- Performing custom validations or transformations
- Integrating with third-party services
- Implementing organization-specific infrastructure patterns

For 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.

## Permissions

The IAM principal used by your Pulumi program must have the following permissions:

1. `lambda:InvokeFunction` on the Lambda function specified in `serviceToken`
2. S3 permissions on the bucket specified in `bucketName`:
- `s3:PutObject`
- `s3:GetObject`
- `s3:HeadObject`

## Lambda Function Requirements

The Lambda function specified in `serviceToken` must implement the CloudFormation Custom Resource lifecycle.
For 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.

## Timeouts

Custom 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.
11 changes: 11 additions & 0 deletions provider/pkg/schema/docs/custom.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
// Copyright 2016-2024, Pulumi Corporation.

package docs

import (
_ "embed"
)

// TODO[pulumi/pulumi-cdk#109] Add examples for the other languages.
//go:embed content/cfn-custom-resource.md
var CfnCustomResourceEmulatorDocs string
3 changes: 2 additions & 1 deletion provider/pkg/schema/gen.go
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ import (
"github.com/pulumi/pulumi-aws-native/provider/pkg/metadata"
"github.com/pulumi/pulumi-aws-native/provider/pkg/naming"
"github.com/pulumi/pulumi-aws-native/provider/pkg/resources"
"github.com/pulumi/pulumi-aws-native/provider/pkg/schema/docs"
"github.com/pulumi/pulumi/pkg/v3/codegen"
dotnetgen "github.com/pulumi/pulumi/pkg/v3/codegen/dotnet"
pschema "github.com/pulumi/pulumi/pkg/v3/codegen/schema"
Expand Down Expand Up @@ -391,7 +392,7 @@ func GatherPackage(supportedResourceTypes []string, jsonSchemas []*jsschema.Sche
},
Resources: map[string]pschema.ResourceSpec{
metadata.ExtensionResourceToken: resources.ExtensionResourceSpec(),
metadata.CfnCustomResourceToken: resources.CfnCustomResourceSpec(),
metadata.CfnCustomResourceToken: resources.CfnCustomResourceSpec(docs.CfnCustomResourceEmulatorDocs),
},
Functions: map[string]pschema.FunctionSpec{},
Language: map[string]pschema.RawMessage{},
Expand Down

0 comments on commit e46c00a

Please sign in to comment.