Add implementation for CloudFormation Custom Resource Emulator

flostadler commented 2 weeks ago

This PR adds support for CloudFormation Custom Resource to the aws-native provider. It implements an emulator that enables Pulumi programs to interact with Lambda-backed CloudFormation Custom Resources.

A CloudFormation custom resource is essentially an extension point to run arbitrary code as part of the CloudFormation lifecycle. It is similar in concept to the Pulumi Command Provider, the difference being that CloudFormation CustomResources are executed in the Cloud; either through Lambda or SNS.

For the first implementation we decided to limit the scope to Lambda backed Custom Resources, because the SNS variants are not widely used.

Custom Resource Protocol

The implementation follows the CloudFormation Custom Resource protocol. I derived the necessary parts by combining information from the docs, CDKs CustomResource Framework and trial&error.

Notable aspects of that protocol are:

primitive properties need to be string encoded when sending them to Custom Resource handlers. This includes deeply nested properties: https://github.com/aws-cloudformation/cloudformation-coverage-roadmap/issues/1037
The Lambda Function is invoked asynchronously. Lambda will retry the execution if the function fails unexpectedly (e.g. unhandled exception).
Due to the async invocation, the response is not returned from the Lambda Function, instead it's sent to a ResponseURL that needs to be included in the request payload.
- Similarly to CloudFormation, we decided to implement this using S3 Buckets and presigned URLs.

Custom Resource Lifecycle

sequenceDiagram
    participant A as aws-native
    participant S3 as S3 Bucket
    participant L as Lambda

    %% Create Flow
    Note over A,L: Create Operation
    A->>S3: Generate presigned URL
    A->>L: Invoke with CREATE event
    activate L
    loop Until response found or timeout
        A->>S3: Poll for response
        L-->>S3: Upload response
    end
    deactivate L
    A->>S3: Fetch response
    alt Success
        A->>A: Store PhysicalId & outputs
    else Failure
        A->>A: Return error
    end

    %% Update Flow
    Note over A,L: Update Operation
    A->>S3: Generate presigned URL
    A->>L: Invoke with UPDATE event
    activate L
    loop Until response found or timeout
        A->>S3: Poll for response
        L-->>S3: Upload response
    end
    deactivate L
    A->>S3: Fetch response
    alt Success
        A->>A: Check PhysicalId
        alt ID Changed
            A->>S3: Generate presigned URL for cleanup
            A->>L: Invoke with DELETE event for old resource
            activate L
            loop Until cleanup response found or timeout
                A->>S3: Poll for cleanup response
                L-->>S3: Upload cleanup response
            end
            deactivate L
            A->>S3: Fetch cleanup response
        end
    else Failure
        A->>A: Return error
    end

    %% Delete Flow
    Note over A,L: Delete Operation
    A->>S3: Generate presigned URL
    A->>L: Invoke with DELETE event
    activate L
    loop Until response found or timeout
        A->>S3: Poll for response
        L-->>S3: Upload response
    end
    deactivate L
    A->>S3: Fetch response
    alt Success
        A->>A: Return success
    else Failure
        A->>A: Return error
    end

Reviewer Notes

Key areas to review:

Error handling in the response collection mechanism
Timeout management, especially for the Update lifecycle
Documentation completeness and accuracy

Exposing this resource and schematizing it is part of this PR https://github.com/pulumi/pulumi-aws-native/pull/1807. Automatically cleaning up the response objects is not included in this PR in order to keep its size manageable. Implementing this is tracked here: https://github.com/pulumi/pulumi-aws-native/issues/1813.

Please pay special attention to:

S3 response collection mechanism security
State management during updates
Cleanup handling when physical resource IDs change

Testing

Unit tests including error handling tests for various failure scenarios
Integration tests with actual Lambda functions are added in this stacked PR: https://github.com/pulumi/pulumi-aws-native/pull/1807

Related Issues

flostadler commented 2 weeks ago

This change is part of the following stack:

1806 ◀
- 1807

_{Change managed by git-spice.}

github-actions[bot] commented 2 weeks ago

Does the PR have any schema changes?

Looking good! No breaking changes found. No new resources/functions.

codecov[bot] commented 2 weeks ago

Codecov Report

Attention: Patch coverage is 59.43152% with 157 lines in your changes missing coverage. Please review.

Project coverage is 48.13%. Comparing base (04539b4) to head (b184dc0). Report is 1 commits behind head on master.

Files with missing lines	Patch %	Lines
provider/pkg/resources/cfn_custom_resource.go	59.43%	142 Missing and 15 partials :warning:

Additional details and impacted files

```diff @@ Coverage Diff @@ ## master #1806 +/- ## ========================================== + Coverage 46.81% 48.13% +1.32% ========================================== Files 42 43 +1 Lines 6167 6554 +387 ========================================== + Hits 2887 3155 +268 - Misses 3052 3156 +104 - Partials 228 243 +15 ```

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

pulumi / pulumi-aws-native