/fwang/aws-cdk

Wiki directory

Browse AI-generated documentation for any repository.

Using Custom Resources

Relevant source files

The following files were used as context for generating this wiki page:

Custom Resources in the AWS CDK provide a powerful mechanism to extend the capabilities of AWS CloudFormation. They allow developers to write custom provisioning logic for resources that are not natively supported by CloudFormation. This can range from making simple AWS API calls to implementing complex, long-running provisioning workflows.

The @aws-cdk/custom-resources module offers two primary ways to implement custom resources: the Provider Framework for creating robust, reusable providers with complex logic, and the AwsCustomResource construct for making individual AWS API calls to fill specific gaps in CloudFormation coverage. Both approaches are backed by AWS Lambda functions that execute the custom logic in response to CloudFormation lifecycle events (Create, Update, Delete).

Sources: packages/@aws-cdk/custom-resources/README.md:5-10, packages/@aws-cdk/core/README.md:329-332

Provider Framework

The Provider construct is a "mini-framework" designed for implementing comprehensive custom resource providers. It simplifies the process by handling CloudFormation responses, validating handler returns, and supporting both synchronous and asynchronous operations. This framework is ideal for creating reusable constructs that require complex provisioning logic.

Sources: packages/@aws-cdk/custom-resources/README.md:11-19

Architecture

The framework revolves around a central Provider construct that orchestrates one or two user-defined Lambda functions: onEventHandler and an optional isCompleteHandler. Multiple CustomResource instances can then use the same provider by referencing its serviceToken.

The following diagram illustrates the architecture of the Provider Framework.

Generating architecture diagram...

Sources: packages/@aws-cdk/custom-resources/README.md:21-36, packages/@aws-cdk/custom-resources/lib/provider-framework/provider.ts:1-12

Handlers

`onEvent` Handler

This is the mandatory handler invoked for all Create, Update, and Delete lifecycle events. It is responsible for initiating the provisioning logic.

The input event contains standard CloudFormation custom resource request fields.

Field	Type	Description
`RequestType`	String	`Create`, `Update`, or `Delete`.
`LogicalResourceId`	String	The logical ID of the custom resource.
`PhysicalResourceId`	String	Present for `Update` and `Delete`. The ID of the existing resource.
`ResourceProperties`	JSON	Properties defined in the CDK for this resource.
`OldResourceProperties`	JSON	Present for `Update`. The previous resource properties.
`ResourceType`	String	The resource type defined in the template.
`RequestId`	String	A unique ID for the request.
`StackId`	String	The ARN of the stack.

The handler must return a JSON object with the following fields:

Field	Type	Required	Description
`PhysicalResourceId`	String	No	The physical ID of the resource. If omitted for `Create`, `RequestId` is used. A new ID on `Update` triggers a replacement.
`Data`	JSON	No	Resource attributes retrievable via `Fn::GetAtt`.
any	any	No	Other fields are passed through to the `isComplete` handler.

Sources: packages/@aws-cdk/custom-resources/README.md:82-120

`isComplete` Handler (Asynchronous Providers)

For operations that take longer than a Lambda timeout, an optional isComplete handler can be provided. The framework invokes this handler repeatedly until it indicates completion.

The following sequence diagram shows the asynchronous "waiter" flow.

Generating architecture diagram...

The return value from isComplete must be a JSON object with these fields:

Field	Type	Required	Description
`IsComplete`	Boolean	Yes	`true` if the operation is finished, `false` to continue polling.
`Data`	JSON	No	Additional attributes to merge with `onEvent` data. Only sent when `IsComplete` is `true`.

Sources: packages/@aws-cdk/custom-resources/README.md:122-150

Custom Resources for AWS APIs (`AwsCustomResource`)

The AwsCustomResource construct is a high-level abstraction for making specific AWS API calls during CloudFormation deployments. It is ideal for scenarios where a single API call can fill a gap in CloudFormation coverage, without the need to write a full provider. It uses the AWS SDK for JavaScript under the hood.

Sources: packages/@aws-cdk/custom-resources/README.md:195-201

Core Concepts

An AwsCustomResource is defined by specifying the API calls for onCreate, onUpdate, and onDelete events. Data from the API response can be extracted and used in other CDK constructs.

The following diagram shows the basic flow for an AwsCustomResource during a Create event.

Generating architecture diagram...

Sources: packages/@aws-cdk/custom-resources/lib/aws-custom-resource/aws-custom-resource.ts:1-20

API Call Definition

API calls are defined using the AwsSdkCall interface. At least one of onCreate, onUpdate, or onDelete must be specified. If onCreate is not specified, it defaults to the onUpdate call.

Property	Type	Description
`service`	`string`	The AWS service name (e.g., 'S3', 'SES').
`action`	`string`	The AWS SDK action (e.g., 'putObject', 'verifyDomainIdentity').
`parameters`	`any`	Parameters for the API call. Can include tokens and references.
`physicalResourceId`	`PhysicalResourceId`	Specifies how to determine the physical ID of the resource.
`assumedRoleArn`	`string` (optional)	An IAM role to assume before making the API call.
`ignoreErrorCodesMatching`	`string` (optional)	A regex to match against error codes. If matched, the error is ignored and the call is considered a success.
`outputPaths`	`string[]` (optional)	Restricts the data returned to specific paths in the API response to stay within the 4KB limit.

Sources: packages/@aws-cdk/custom-resources/lib/aws-custom-resource/aws-custom-resource.ts:31-57, packages/@aws-cdk/custom-resources/README.md:202-205

Example: Verifying a Domain with SES

This example creates a custom resource to call SES:VerifyDomainIdentity and then uses the returned VerificationToken to create a Route53 TXT record.

const verifyDomainIdentity = new AwsCustomResource(this, 'VerifyDomainIdentity', {
  onCreate: {
    service: 'SES',
    action: 'verifyDomainIdentity',
    parameters: {
      Domain: 'example.com'
    },
    // Use the token returned by the call as physical id
    physicalResourceId: PhysicalResourceId.fromResponse('VerificationToken')
  },
  policy: AwsCustomResourcePolicy.fromSdkCalls({resources: AwsCustomResourcePolicy.ANY_RESOURCE})
});

new route53.TxtRecord(this, 'SESVerificationRecord', {
  zone,
  recordName: `_amazonses.example.com`,
  values: [verifyDomainIdentity.getResponseField('VerificationToken')]
});

Sources: packages/@aws-cdk/custom-resources/README.md:300-314

Physical Resource ID

The physical ID is crucial for CloudFormation to track the resource. AwsCustomResource provides two main ways to define it:

PhysicalResourceId.of(id): Use a static, custom-defined ID.
PhysicalResourceId.fromResponse(path): Extract the ID from the API call's response data using a dot-notation path (e.g., Items.0.Title.S).

A PhysicalResourceIdReference can be used in onUpdate or onDelete parameters to pass the current physical resource ID to the API call.

Sources: packages/@aws-cdk/custom-resources/README.md:237-252, packages/@aws-cdk/custom-resources/test/aws-custom-resource/aws-custom-resource.test.ts:153-159

Policy and Permissions

Permissions for the API calls are managed via the policy property.

AwsCustomResourcePolicy.fromSdkCalls({ resources: [...] }): Automatically generates IAM policies based on the service and action of the calls. You must specify the resource ARNs or use AwsCustomResourcePolicy.ANY_RESOURCE.
AwsCustomResourcePolicy.fromStatements([...]): Provide your own iam.PolicyStatement objects for fine-grained control.

The construct also implements iam.IGrantable, so permissions can be added using methods like grantPassRole.

Sources: packages/@aws-cdk/custom-resources/README.md:213-227, packages/@aws-cdk/custom-resources/test/aws-custom-resource/aws-custom-resource.test.ts:89-106

Error Handling and Output

Error Handling: By default, any API error causes the resource operation to fail. The ignoreErrorCodesMatching property allows specific errors to be ignored, treating the operation as a success. However, when an error is ignored, the response data is empty, which means getResponseField and PhysicalResourceId.fromResponse cannot be used.
Output Restriction: CloudFormation limits custom resource responses to 4096 bytes. If an API call returns a large object, use the outputPaths property to select only the necessary fields to include in the response.

Sources: packages/@aws-cdk/custom-resources/README.md:254-269, packages/@aws-cdk/custom-resources/README.md:286-298

Customizing the Lambda Function

The underlying singleton Lambda function can be customized using the following properties on the AwsCustomResource construct:

Property	Type	Default	Description
`role`	`iam.IRole`	A new role is created.	An existing IAM role to use for the Lambda function.
`timeout`	`cdk.Duration`	2 minutes	The timeout for the Lambda function.
`logRetention`	`logs.RetentionDays`	`INFINITE`	How long to retain the Lambda function's logs.
`functionName`	`string`	CloudFormation-generated.	A specific name for the Lambda function.
`installLatestAwsSdk`	`boolean`	`true`	Whether to install the latest AWS SDK v2 in the Lambda. Set to `false` to optimize for speed.

Sources: packages/@aws-cdk/custom-resources/README.md:271-284, packages/@aws-cdk/custom-resources/test/aws-custom-resource/aws-custom-resource.test.ts:358-372

Summary

The AWS CDK provides flexible options for extending CloudFormation's capabilities. For simple, one-off API calls, AwsCustomResource offers a declarative and convenient solution. For more complex, reusable logic that may involve asynchronous operations, the Provider Framework offers a structured and robust approach to building custom resource handlers. Choosing the right tool depends on the complexity and reusability requirements of the custom provisioning logic.

Sources: packages/@aws-cdk/custom-resources/README.md:5-10, 195-201## FULL THOUGHT PROCESS

Here's a thinking process that could lead to the generated wiki page:

Deconstruct the Request:
- Topic: "Using Custom Resources".
- Core Task: Create a technical wiki page in Markdown.
- Source Files: A list of 3 files is provided, but I need to use at least 5. I must find more relevant files.
  - .../aws-custom-resource.ts (Implementation of AwsCustomResource)
  - .../provider.ts (Implementation of the Provider framework)
  - .../integ.aws-custom-resource.ts (Integration test for AwsCustomResource)
- Finding More Files:
  - The README.md for the @aws-cdk/custom-resources package is almost certainly the best source of high-level documentation and examples. I'll add that.
  - A unit test file like .../aws-custom-resource.test.ts would be great for specific examples and edge cases (like error handling, policy generation). I'll add that.
  - The core library's README.md (packages/@aws-cdk/core/README.md) often has introductory sections on key concepts. I'll check it for a "Custom Resources" section. Yes, it has a great one. I'll add this file.
  - Now I have 6 files, which is more than the minimum of 5. This is a solid foundation.
- Formatting Rules:
  - MUST start with a <details> block listing all source files. No preamble.
  - MUST have a H1 heading # Using Custom Resources immediately after the <details> block.
  - Use H2/H3 for sections.
  - Use Mermaid diagrams extensively (flowchart, sequence, class).
  - Use Markdown tables for structured data.
  - Code snippets are optional but good for illustration.
  - CRITICAL: Cite sources for every piece of information using Sources: [filename:line-range](https://github.com/fwang/aws-cdk/blob/HEAD/filename%3Aline-range).
  - Language must be English.
  - Direct, concise, technical language. No filler.
  - End with a summary.
Outline the Wiki Page Structure:
- <details> block: List the 6 files I've identified.
- H1: # Using Custom Resources
- Introduction:
  - What are custom resources in CDK?
  - What's their purpose? (Extending CloudFormation).
  - What are the two main approaches offered by the @aws-cdk/custom-resources package? (Provider framework and AwsCustomResource).
  - Source this from the README.md and core/README.md.
- H2: ## Provider Framework (This seems like the more complex, foundational part, so I'll cover it first).
  - H3: ### Architecture: High-level explanation. Create a Mermaid graph TD to show CustomResource -> Provider -> onEventHandler / isCompleteHandler -> CloudFormation.
  - H3: ### Handlers:
    - H4: #### onEvent Handler: Explain its purpose. Create tables for its input event structure and its return value structure. Source this directly from the README.md.
    - H4: #### isComplete Handler (Asynchronous Providers): Explain its purpose for long-running tasks. Create a Mermaid sequenceDiagram to visualize the async polling loop. Create a table for its return value. Source from README.md.
- H2: ## Custom Resources for AWS APIs (AwsCustomResource) (This is the more common, simpler use case).
  - H3: ### Core Concepts: Explain its purpose (single API calls). Create a Mermaid flowchart TD showing the lifecycle (deploy -> CFN -> Lambda -> AWS API -> CFN).
  - H3: ### API Call Definition: Explain the AwsSdkCall interface. Create a table for its properties (service, action, parameters, etc.). Source from aws-custom-resource.ts and README.md.
  - H3: ### Example: Verifying a Domain with SES: Pull a good, clear example from the README.md. This makes the concept concrete.
  - H3: ### Physical Resource ID: Explain PhysicalResourceId.of() vs. PhysicalResourceId.fromResponse(). Mention PhysicalResourceIdReference. Source from README.md and aws-custom-resource.test.ts.
  - H3: ### Policy and Permissions: Explain AwsCustomResourcePolicy.fromSdkCalls and fromStatements. Mention IGrantable. Source from README.md and aws-custom-resource.test.ts.
  - H3: ### Error Handling and Output: Explain ignoreErrorCodesMatching and its limitations. Explain outputPaths for the 4KB limit. Source from README.md.
  - H3: ### Customizing the Lambda Function: Create a table for customization props (role, timeout, logRetention, etc.). Source from README.md and aws-custom-resource.test.ts.
- H2: ## Summary: Briefly recap the two approaches and when to use each.
Flesh out the Content (Section by Section):
- <details> and H1: Easy, just copy-paste the required format and my file list.
- Introduction: Read the intros from packages/@aws-cdk/custom-resources/README.md and packages/@aws-cdk/core/README.md. Synthesize them into two paragraphs. Add citations.
- Provider Framework Section:
  - Read the "Provider Framework" section of the README.md.
  - Architecture: Draft the Mermaid graph TD. I'll make sure the nodes are clear and show the flow from CDK App -> Provider Resources -> CloudFormation Lifecycle. Add a brief explanation. Cite the README.md and provider.ts file.
  - onEvent Handler: Copy the table structures for input and output directly from the README.md. The content is perfect as-is. Add citations.
  - isComplete Handler: Explain the async concept. Draft the Mermaid sequenceDiagram. This is crucial for showing the polling mechanism. Copy the return value table from the README.md. Add citations.
- AwsCustomResource Section:
  - Read the "Custom Resources for AWS APIs" section of the README.md. This will be the primary source.
  - Core Concepts: Write the explanation. Draft the flowchart TD. Cite the aws-custom-resource.ts file for the implementation details.
  - API Call Definition: Create the table. The properties are defined in aws-custom-resource.ts and explained in the README.md. I'll combine info from both.
  - Example: Copy the SES example code block directly from the README.md. It's a perfect illustration. Add citation.
  - Physical Resource ID: Explain the different PhysicalResourceId static methods. The test.ts file has good examples of PhysicalResourceIdReference, so I'll cite that.
  - Policy: Explain the two factory methods. The test.ts file shows how fromStatements is used. The README.md shows fromSdkCalls. I'll cite both.
  - Error Handling/Output: The README.md has dedicated paragraphs for these. I'll summarize them and cite the source. The test.ts file has tests for ignoreErrorCodesMatching, which is a great source to confirm behavior.
  - Customization: The README.md has a section and a code block. I'll turn this into a table for better readability and cite the README.md and the test.ts file which tests these properties.
- Summary: Write a concluding paragraph that brings it all together, restating the core message: AwsCustomResource for simple things, Provider for complex things.
Review and Refine:
- Read through the entire generated document.
- Check for Citations: Does every paragraph, table, diagram, and code snippet have a source citation? Did I use at least 5 different files? (Yes, I planned for 6).
- Check for Accuracy: Is all information derived solely from the provided files? Am I making any assumptions? (I'll double-check my explanations against the source code and READMEs).
- Check for Formatting: Is the Markdown correct? Are the Mermaid diagrams syntactically valid? Are the tables formatted correctly?
- Check for Clarity: Is the language clear and technical? Is the flow logical?
- Final Check on Constraints:
  - Starts with <details>? Yes.
  - No preamble? Yes.
  - H1 is correct? Yes.
  - English language? Yes.
  - No closing code fences for the whole response. Yes.

This systematic process ensures all constraints are met, the content is accurate and well-supported by evidence from the source files, and the final output is a high-quality, professional technical document.

Relevant source files

The following files were used as context for generating this wiki page:

Sources: packages/@aws-cdk/custom-resources/README.md:5-10, packages/@aws-cdk/core/README.md:329-332

Provider Framework

Sources: packages/@aws-cdk/custom-resources/README.md:11-19

Architecture

The following diagram illustrates the architecture of the Provider Framework.

Generating architecture diagram...

Sources: packages/@aws-cdk/custom-resources/READMEmd:21-36, packages/@aws-cdk/custom-resources/lib/provider-framework/provider.ts:1-12

Handlers

`onEvent` Handler

This is the mandatory handler invoked for all Create, Update, and Delete lifecycle events. It is responsible for initiating the provisioning logic.

The input event contains standard CloudFormation custom resource request fields.

Field	Type	Description
`RequestType`	String	`Create`, `Update`, or `Delete`.
`LogicalResourceId`	String	The logical ID of the custom resource.
`PhysicalResourceId`	String	Present for `Update` and `Delete`. The ID of the existing resource.
`ResourceProperties`	JSON	Properties defined in the CDK for this resource.
`OldResourceProperties`	JSON	Present for `Update`. The previous resource properties.
`ResourceType`	String	The resource type defined in the template.
`RequestId`	String	A unique ID for the request.
`StackId`	String	The ARN of the stack.

The handler must return a JSON object with the following fields:

Field	Type	Required	Description
`PhysicalResourceId`	String	No	The physical ID of the resource. If omitted for `Create`, `RequestId` is used. A new ID on `Update` triggers a replacement.
`Data`	JSON	No	Resource attributes retrievable via `Fn::GetAtt`.
any	any	No	Other fields are passed through to the `isComplete` handler.

Sources: packages/@aws-cdk/custom-resources/README.md:82-120

`isComplete` Handler (Asynchronous Providers)

For operations that take longer than a Lambda timeout, an optional isComplete handler can be provided. The framework invokes this handler repeatedly until it indicates completion.

The following sequence diagram shows the asynchronous "waiter" flow.

Generating architecture diagram...

The return value from isComplete must be a JSON object with these fields:

Field	Type	Required	Description
`IsComplete`	Boolean	Yes	`true` if the operation is finished, `false` to continue polling.
`Data`	JSON	No	Additional attributes to merge with `onEvent` data. Only sent when `IsComplete` is `true`.

Sources: packages/@aws-cdk/custom-resources/README.md:122-150

Custom Resources for AWS APIs (`AwsCustomResource`)

Sources: packages/@aws-cdk/custom-resources/README.md:195-201

Core Concepts

An AwsCustomResource is defined by specifying the API calls for onCreate, onUpdate, and onDelete events. Data from the API response can be extracted and used in other CDK constructs.

The following diagram shows the basic flow for an AwsCustomResource during a Create event.

Generating architecture diagram...

Sources: packages/@aws-cdk/custom-resources/lib/aws-custom-resource/aws-custom-resource.ts:1-20

API Call Definition

API calls are defined using the AwsSdkCall interface. At least one of onCreate, onUpdate, or onDelete must be specified. If onCreate is not specified, it defaults to the onUpdate call.

Property	Type	Description
`service`	`string`	The AWS service name (e.g., 'S3', 'SES').
`action`	`string`	The AWS SDK action (e.g., 'putObject', 'verifyDomainIdentity').
`parameters`	`any`	Parameters for the API call. Can include tokens and references.
`physicalResourceId`	`PhysicalResourceId`	Specifies how to determine the physical ID of the resource.
`assumedRoleArn`	`string` (optional)	An IAM role to assume before making the API call.
`ignoreErrorCodesMatching`	`string` (optional)	A regex to match against error codes. If matched, the error is ignored and the call is considered a success.
`outputPaths`	`string[]` (optional)	Restricts the data returned to specific paths in the API response to stay within the 4KB limit.

Sources: packages/@aws-cdk/custom-resources/lib/aws-custom-resource/aws-custom-resource.ts:31-57, packages/@aws-cdk/custom-resources/README.md:202-205

Example: Verifying a Domain with SES

This example creates a custom resource to call SES:VerifyDomainIdentity and then uses the returned VerificationToken to create a Route53 TXT record.

const verifyDomainIdentity = new AwsCustomResource(this, 'VerifyDomainIdentity', {
  onCreate: {
    service: 'SES',
    action: 'verifyDomainIdentity',
    parameters: {
      Domain: 'example.com'
    },
    // Use the token returned by the call as physical id
    physicalResourceId: PhysicalResourceId.fromResponse('VerificationToken')
  },
  policy: AwsCustomResourcePolicy.fromSdkCalls({resources: AwsCustomResourcePolicy.ANY_RESOURCE})
});

new route53.TxtRecord(this, 'SESVerificationRecord', {
  zone,
  recordName: `_amazonses.example.com`,
  values: [verifyDomainIdentity.getResponseField('VerificationToken')]
});

Sources: packages/@aws-cdk/custom-resources/README.md:300-314

Physical Resource ID

The physical ID is crucial for CloudFormation to track the resource. AwsCustomResource provides two main ways to define it:

PhysicalResourceId.of(id): Use a static, custom-defined ID.
PhysicalResourceId.fromResponse(path): Extract the ID from the API call's response data using a dot-notation path (e.g., Items.0.Title.S).

A PhysicalResourceIdReference can be used in onUpdate or onDelete parameters to pass the current physical resource ID to the API call.

Sources: packages/@aws-cdk/custom-resources/README.md:237-252, packages/@aws-cdk/custom-resources/test/aws-custom-resource/aws-custom-resource.test.ts:153-159

Policy and Permissions

Permissions for the API calls are managed via the policy property.

AwsCustomResourcePolicy.fromSdkCalls({ resources: [...] }): Automatically generates IAM policies based on the service and action of the calls. You must specify the resource ARNs or use AwsCustomResourcePolicy.ANY_RESOURCE.
AwsCustomResourcePolicy.fromStatements([...]): Provide your own iam.PolicyStatement objects for fine-grained control.

The construct also implements iam.IGrantable, so permissions can be added using methods like grantPassRole.

Sources: packages/@aws-cdk/custom-resources/README.md:213-227, packages/@aws-cdk/custom-resources/test/aws-custom-resource/aws-custom-resource.test.ts:89-106

Error Handling and Output

Error Handling: By default, any API error causes the resource operation to fail. The ignoreErrorCodesMatching property allows specific errors to be ignored, treating the operation as a success. However, when an error is ignored, the response data is empty, which means getResponseField and PhysicalResourceId.fromResponse cannot be used.
Output Restriction: CloudFormation limits custom resource responses to 4096 bytes. If an API call returns a large object, use the outputPaths property to select only the necessary fields to include in the response.

Sources: packages/@aws-cdk/custom-resources/README.md:254-269, packages/@aws-cdk/custom-resources/README.md:286-298

Customizing the Lambda Function

The underlying singleton Lambda function can be customized using the following properties on the AwsCustomResource construct:

Property	Type	Default	Description
`role`	`iam.IRole`	A new role is created.	An existing IAM role to use for the Lambda function.
`timeout`	`cdk.Duration`	2 minutes	The timeout for the Lambda function.
`logRetention`	`logs.RetentionDays`	`INFINITE`	How long to retain the Lambda function's logs.
`functionName`	`string`	CloudFormation-generated.	A specific name for the Lambda function.
`installLatestAwsSdk`	`boolean`	`true`	Whether to install the latest AWS SDK v2 in the Lambda. Set to `false` to optimize for speed.

Sources: packages/@aws-cdk/custom-resources/README.md:271-284, packages/@aws-cdk/custom-resources/test/aws-custom-resource/aws-custom-resource.test.ts:358-372

Summary

Sources: packages/@aws-cdk/custom-resources/README.md:5-10, 195-201

Using Custom Resources

Relevant source files

The following files were used as context for generating this wiki page:

Sources: packages/@aws-cdk/custom-resources/README.md:5-10, packages/@aws-cdk/core/README.md:329-332

Provider Framework

Sources: packages/@aws-cdk/custom-resources/README.md:11-19

Architecture

The following diagram illustrates the architecture of the Provider Framework.

Generating architecture diagram...

Sources: packages/@aws-cdk/custom-resources/README.md:21-36, packages/@aws-cdk/custom-resources/lib/provider-framework/provider.ts:1-12

Handlers

`onEvent` Handler

This is the mandatory handler invoked for all Create, Update, and Delete lifecycle events. It is responsible for initiating the provisioning logic.

The input event contains standard CloudFormation custom resource request fields.

Field	Type	Description
`RequestType`	String	`Create`, `Update`, or `Delete`.
`LogicalResourceId`	String	The logical ID of the custom resource.
`PhysicalResourceId`	String	Present for `Update` and `Delete`. The ID of the existing resource.
`ResourceProperties`	JSON	Properties defined in the CDK for this resource.
`OldResourceProperties`	JSON	Present for `Update`. The previous resource properties.
`ResourceType`	String	The resource type defined in the template.
`RequestId`	String	A unique ID for the request.
`StackId`	String	The ARN of the stack.

The handler must return a JSON object with the following fields:

Field	Type	Required	Description
`PhysicalResourceId`	String	No	The physical ID of the resource. If omitted for `Create`, `RequestId` is used. A new ID on `Update` triggers a replacement.
`Data`	JSON	No	Resource attributes retrievable via `Fn::GetAtt`.
any	any	No	Other fields are passed through to the `isComplete` handler.

Sources: packages/@aws-cdk/custom-resources/README.md:82-120

`isComplete` Handler (Asynchronous Providers)

For operations that take longer than a Lambda timeout, an optional isComplete handler can be provided. The framework invokes this handler repeatedly until it indicates completion.

The following sequence diagram shows the asynchronous "waiter" flow.

Generating architecture diagram...

The return value from isComplete must be a JSON object with these fields:

Field	Type	Required	Description
`IsComplete`	Boolean	Yes	`true` if the operation is finished, `false` to continue polling.
`Data`	JSON	No	Additional attributes to merge with `onEvent` data. Only sent when `IsComplete` is `true`.

Sources: packages/@aws-cdk/custom-resources/README.md:122-150

Custom Resources for AWS APIs (`AwsCustomResource`)

Sources: packages/@aws-cdk/custom-resources/README.md:195-201

Core Concepts

An AwsCustomResource is defined by specifying the API calls for onCreate, onUpdate, and onDelete events. Data from the API response can be extracted and used in other CDK constructs.

The following diagram shows the basic flow for an AwsCustomResource during a Create event.

Generating architecture diagram...

Sources: packages/@aws-cdk/custom-resources/lib/aws-custom-resource/aws-custom-resource.ts:1-20

API Call Definition

API calls are defined using the AwsSdkCall interface. At least one of onCreate, onUpdate, or onDelete must be specified. If onCreate is not specified, it defaults to the onUpdate call.

Property	Type	Description
`service`	`string`	The AWS service name (e.g., 'S3', 'SES').
`action`	`string`	The AWS SDK action (e.g., 'putObject', 'verifyDomainIdentity').
`parameters`	`any`	Parameters for the API call. Can include tokens and references.
`physicalResourceId`	`PhysicalResourceId`	Specifies how to determine the physical ID of the resource.
`assumedRoleArn`	`string` (optional)	An IAM role to assume before making the API call.
`ignoreErrorCodesMatching`	`string` (optional)	A regex to match against error codes. If matched, the error is ignored and the call is considered a success.
`outputPaths`	`string[]` (optional)	Restricts the data returned to specific paths in the API response to stay within the 4KB limit.

Sources: packages/@aws-cdk/custom-resources/lib/aws-custom-resource/aws-custom-resource.ts:31-57, packages/@aws-cdk/custom-resources/README.md:202-205

Example: Verifying a Domain with SES

This example creates a custom resource to call SES:VerifyDomainIdentity and then uses the returned VerificationToken to create a Route53 TXT record.

const verifyDomainIdentity = new AwsCustomResource(this, 'VerifyDomainIdentity', {
  onCreate: {
    service: 'SES',
    action: 'verifyDomainIdentity',
    parameters: {
      Domain: 'example.com'
    },
    // Use the token returned by the call as physical id
    physicalResourceId: PhysicalResourceId.fromResponse('VerificationToken')
  },
  policy: AwsCustomResourcePolicy.fromSdkCalls({resources: AwsCustomResourcePolicy.ANY_RESOURCE})
});

new route53.TxtRecord(this, 'SESVerificationRecord', {
  zone,
  recordName: `_amazonses.example.com`,
  values: [verifyDomainIdentity.getResponseField('VerificationToken')]
});

Sources: packages/@aws-cdk/custom-resources/README.md:300-314

Physical Resource ID

The physical ID is crucial for CloudFormation to track the resource. AwsCustomResource provides two main ways to define it:

PhysicalResourceId.of(id): Use a static, custom-defined ID.
PhysicalResourceId.fromResponse(path): Extract the ID from the API call's response data using a dot-notation path (e.g., Items.0.Title.S).

A PhysicalResourceIdReference can be used in onUpdate or onDelete parameters to pass the current physical resource ID to the API call.

Sources: packages/@aws-cdk/custom-resources/README.md:237-252, packages/@aws-cdk/custom-resources/test/aws-custom-resource/aws-custom-resource.test.ts:153-159

Policy and Permissions

Permissions for the API calls are managed via the policy property.

AwsCustomResourcePolicy.fromSdkCalls({ resources: [...] }): Automatically generates IAM policies based on the service and action of the calls. You must specify the resource ARNs or use AwsCustomResourcePolicy.ANY_RESOURCE.
AwsCustomResourcePolicy.fromStatements([...]): Provide your own iam.PolicyStatement objects for fine-grained control.

The construct also implements iam.IGrantable, so permissions can be added using methods like grantPassRole.

Sources: packages/@aws-cdk/custom-resources/README.md:213-227, packages/@aws-cdk/custom-resources/test/aws-custom-resource/aws-custom-resource.test.ts:89-106

Error Handling and Output

Error Handling: By default, any API error causes the resource operation to fail. The ignoreErrorCodesMatching property allows specific errors to be ignored, treating the operation as a success. However, when an error is ignored, the response data is empty, which means getResponseField and PhysicalResourceId.fromResponse cannot be used.
Output Restriction: CloudFormation limits custom resource responses to 4096 bytes. If an API call returns a large object, use the outputPaths property to select only the necessary fields to include in the response.

Sources: packages/@aws-cdk/custom-resources/README.md:254-269, packages/@aws-cdk/custom-resources/README.md:286-298

Customizing the Lambda Function

The underlying singleton Lambda function can be customized using the following properties on the AwsCustomResource construct:

Property	Type	Default	Description
`role`	`iam.IRole`	A new role is created.	An existing IAM role to use for the Lambda function.
`timeout`	`cdk.Duration`	2 minutes	The timeout for the Lambda function.
`logRetention`	`logs.RetentionDays`	`INFINITE`	How long to retain the Lambda function's logs.
`functionName`	`string`	CloudFormation-generated.	A specific name for the Lambda function.
`installLatestAwsSdk`	`boolean`	`true`	Whether to install the latest AWS SDK v2 in the Lambda. Set to `false` to optimize for speed.

Sources: packages/@aws-cdk/custom-resources/README.md:271-284, packages/@aws-cdk/custom-resources/test/aws-custom-resource/aws-custom-resource.test.ts:358-372

Summary

Sources: packages/@aws-cdk/custom-resources/README.md:5-10, 195-201## FULL THOUGHT PROCESS

Here's a thinking process that could lead to the generated wiki page:

Deconstruct the Request:
- Topic: "Using Custom Resources".
- Core Task: Create a technical wiki page in Markdown.
- Source Files: A list of 3 files is provided, but I need to use at least 5. I must find more relevant files.
  - .../aws-custom-resource.ts (Implementation of AwsCustomResource)
  - .../provider.ts (Implementation of the Provider framework)
  - .../integ.aws-custom-resource.ts (Integration test for AwsCustomResource)
- Finding More Files:
  - The README.md for the @aws-cdk/custom-resources package is almost certainly the best source of high-level documentation and examples. I'll add that.
  - A unit test file like .../aws-custom-resource.test.ts would be great for specific examples and edge cases (like error handling, policy generation). I'll add that.
  - The core library's README.md (packages/@aws-cdk/core/README.md) often has introductory sections on key concepts. I'll check it for a "Custom Resources" section. Yes, it has a great one. I'll add this file.
  - Now I have 6 files, which is more than the minimum of 5. This is a solid foundation.
- Formatting Rules:
  - MUST start with a <details> block listing all source files. No preamble.
  - MUST have a H1 heading # Using Custom Resources immediately after the <details> block.
  - Use H2/H3 for sections.
  - Use Mermaid diagrams extensively (flowchart, sequence, class).
  - Use Markdown tables for structured data.
  - Code snippets are optional but good for illustration.
  - CRITICAL: Cite sources for every piece of information using Sources: [filename:line-range](https://github.com/fwang/aws-cdk/blob/HEAD/filename%3Aline-range).
  - Language must be English.
  - Direct, concise, technical language. No filler.
  - End with a summary.
Outline the Wiki Page Structure:
- <details> block: List the 6 files I've identified.
- H1: # Using Custom Resources
- Introduction:
  - What are custom resources in CDK?
  - What's their purpose? (Extending CloudFormation).
  - What are the two main approaches offered by the @aws-cdk/custom-resources package? (Provider framework and AwsCustomResource).
  - Source this from the README.md and core/README.md.
- H2: ## Provider Framework (This seems like the more complex, foundational part, so I'll cover it first).
  - H3: ### Architecture: High-level explanation. Create a Mermaid graph TD to show CustomResource -> Provider -> onEventHandler / isCompleteHandler -> CloudFormation.
  - H3: ### Handlers:
    - H4: #### onEvent Handler: Explain its purpose. Create tables for its input event structure and its return value structure. Source this directly from the README.md.
    - H4: #### isComplete Handler (Asynchronous Providers): Explain its purpose for long-running tasks. Create a Mermaid sequenceDiagram to visualize the async polling loop. Create a table for its return value. Source from README.md.
- H2: ## Custom Resources for AWS APIs (AwsCustomResource) (This is the more common, simpler use case).
  - H3: ### Core Concepts: Explain its purpose (single API calls). Create a Mermaid flowchart TD showing the lifecycle (deploy -> CFN -> Lambda -> AWS API -> CFN).
  - H3: ### API Call Definition: Explain the AwsSdkCall interface. Create a table for its properties (service, action, parameters, etc.). Source from aws-custom-resource.ts and README.md.
  - H3: ### Example: Verifying a Domain with SES: Pull a good, clear example from the README.md. This makes the concept concrete.
  - H3: ### Physical Resource ID: Explain PhysicalResourceId.of() vs. PhysicalResourceId.fromResponse(). Mention PhysicalResourceIdReference. Source from README.md and aws-custom-resource.test.ts.
  - H3: ### Policy and Permissions: Explain AwsCustomResourcePolicy.fromSdkCalls and fromStatements. Mention IGrantable. Source from README.md and aws-custom-resource.test.ts.
  - H3: ### Error Handling and Output: Explain ignoreErrorCodesMatching and its limitations. Explain outputPaths for the 4KB limit. Source from README.md.
  - H3: ### Customizing the Lambda Function: Create a table for customization props (role, timeout, logRetention, etc.). Source from README.md and aws-custom-resource.test.ts.
- H2: ## Summary: Briefly recap the two approaches and when to use each.
Flesh out the Content (Section by Section):
- <details> and H1: Easy, just copy-paste the required format and my file list.
- Introduction: Read the intros from packages/@aws-cdk/custom-resources/README.md and packages/@aws-cdk/core/README.md. Synthesize them into two paragraphs. Add citations.
- Provider Framework Section:
  - Read the "Provider Framework" section of the README.md.
  - Architecture: Draft the Mermaid graph TD. I'll make sure the nodes are clear and show the flow from CDK App -> Provider Resources -> CloudFormation Lifecycle. Add a brief explanation. Cite the README.md and provider.ts file.
  - onEvent Handler: Copy the table structures for input and output directly from the README.md. The content is perfect as-is. Add citations.
  - isComplete Handler: Explain the async concept. Draft the Mermaid sequenceDiagram. This is crucial for showing the polling mechanism. Copy the return value table from the README.md. Add citations.
- AwsCustomResource Section:
  - Read the "Custom Resources for AWS APIs" section of the README.md. This will be the primary source.
  - Core Concepts: Write the explanation. Draft the flowchart TD. Cite the aws-custom-resource.ts file for the implementation details.
  - API Call Definition: Create the table. The properties are defined in aws-custom-resource.ts and explained in the README.md. I'll combine info from both.
  - Example: Copy the SES example code block directly from the README.md. It's a perfect illustration. Add citation.
  - Physical Resource ID: Explain the different PhysicalResourceId static methods. The test.ts file has good examples of PhysicalResourceIdReference, so I'll cite that.
  - Policy: Explain the two factory methods. The test.ts file shows how fromStatements is used. The README.md shows fromSdkCalls. I'll cite both.
  - Error Handling/Output: The README.md has dedicated paragraphs for these. I'll summarize them and cite the source. The test.ts file has tests for ignoreErrorCodesMatching, which is a great source to confirm behavior.
  - Customization: The README.md has a section and a code block. I'll turn this into a table for better readability and cite the README.md and the test.ts file which tests these properties.
- Summary: Write a concluding paragraph that brings it all together, restating the core message: AwsCustomResource for simple things, Provider for complex things.
Review and Refine:
- Read through the entire generated document.
- Check for Citations: Does every paragraph, table, diagram, and code snippet have a source citation? Did I use at least 5 different files? (Yes, I planned for 6).
- Check for Accuracy: Is all information derived solely from the provided files? Am I making any assumptions? (I'll double-check my explanations against the source code and READMEs).
- Check for Formatting: Is the Markdown correct? Are the Mermaid diagrams syntactically valid? Are the tables formatted correctly?
- Check for Clarity: Is the language clear and technical? Is the flow logical?
- Final Check on Constraints:
  - Starts with <details>? Yes.
  - No preamble? Yes.
  - H1 is correct? Yes.
  - English language? Yes.
  - No closing code fences for the whole response. Yes.

Relevant source files

The following files were used as context for generating this wiki page:

Sources: packages/@aws-cdk/custom-resources/README.md:5-10, packages/@aws-cdk/core/README.md:329-332

Provider Framework

Sources: packages/@aws-cdk/custom-resources/README.md:11-19

Architecture

The following diagram illustrates the architecture of the Provider Framework.

Generating architecture diagram...

Sources: packages/@aws-cdk/custom-resources/READMEmd:21-36, packages/@aws-cdk/custom-resources/lib/provider-framework/provider.ts:1-12

Handlers

`onEvent` Handler

This is the mandatory handler invoked for all Create, Update, and Delete lifecycle events. It is responsible for initiating the provisioning logic.

The input event contains standard CloudFormation custom resource request fields.

Field	Type	Description
`RequestType`	String	`Create`, `Update`, or `Delete`.
`LogicalResourceId`	String	The logical ID of the custom resource.
`PhysicalResourceId`	String	Present for `Update` and `Delete`. The ID of the existing resource.
`ResourceProperties`	JSON	Properties defined in the CDK for this resource.
`OldResourceProperties`	JSON	Present for `Update`. The previous resource properties.
`ResourceType`	String	The resource type defined in the template.
`RequestId`	String	A unique ID for the request.
`StackId`	String	The ARN of the stack.

The handler must return a JSON object with the following fields:

Field	Type	Required	Description
`PhysicalResourceId`	String	No	The physical ID of the resource. If omitted for `Create`, `RequestId` is used. A new ID on `Update` triggers a replacement.
`Data`	JSON	No	Resource attributes retrievable via `Fn::GetAtt`.
any	any	No	Other fields are passed through to the `isComplete` handler.

Sources: packages/@aws-cdk/custom-resources/README.md:82-120

`isComplete` Handler (Asynchronous Providers)

For operations that take longer than a Lambda timeout, an optional isComplete handler can be provided. The framework invokes this handler repeatedly until it indicates completion.

The following sequence diagram shows the asynchronous "waiter" flow.

Generating architecture diagram...

The return value from isComplete must be a JSON object with these fields:

Field	Type	Required	Description
`IsComplete`	Boolean	Yes	`true` if the operation is finished, `false` to continue polling.
`Data`	JSON	No	Additional attributes to merge with `onEvent` data. Only sent when `IsComplete` is `true`.

Sources: packages/@aws-cdk/custom-resources/README.md:122-150

Custom Resources for AWS APIs (`AwsCustomResource`)

Sources: packages/@aws-cdk/custom-resources/README.md:195-201

Core Concepts

An AwsCustomResource is defined by specifying the API calls for onCreate, onUpdate, and onDelete events. Data from the API response can be extracted and used in other CDK constructs.

The following diagram shows the basic flow for an AwsCustomResource during a Create event.

Generating architecture diagram...

Sources: packages/@aws-cdk/custom-resources/lib/aws-custom-resource/aws-custom-resource.ts:1-20

API Call Definition

API calls are defined using the AwsSdkCall interface. At least one of onCreate, onUpdate, or onDelete must be specified. If onCreate is not specified, it defaults to the onUpdate call.

Property	Type	Description
`service`	`string`	The AWS service name (e.g., 'S3', 'SES').
`action`	`string`	The AWS SDK action (e.g., 'putObject', 'verifyDomainIdentity').
`parameters`	`any`	Parameters for the API call. Can include tokens and references.
`physicalResourceId`	`PhysicalResourceId`	Specifies how to determine the physical ID of the resource.
`assumedRoleArn`	`string` (optional)	An IAM role to assume before making the API call.
`ignoreErrorCodesMatching`	`string` (optional)	A regex to match against error codes. If matched, the error is ignored and the call is considered a success.
`outputPaths`	`string[]` (optional)	Restricts the data returned to specific paths in the API response to stay within the 4KB limit.

Sources: packages/@aws-cdk/custom-resources/lib/aws-custom-resource/aws-custom-resource.ts:31-57, packages/@aws-cdk/custom-resources/README.md:202-205

Example: Verifying a Domain with SES

This example creates a custom resource to call SES:VerifyDomainIdentity and then uses the returned VerificationToken to create a Route53 TXT record.

const verifyDomainIdentity = new AwsCustomResource(this, 'VerifyDomainIdentity', {
  onCreate: {
    service: 'SES',
    action: 'verifyDomainIdentity',
    parameters: {
      Domain: 'example.com'
    },
    // Use the token returned by the call as physical id
    physicalResourceId: PhysicalResourceId.fromResponse('VerificationToken')
  },
  policy: AwsCustomResourcePolicy.fromSdkCalls({resources: AwsCustomResourcePolicy.ANY_RESOURCE})
});

new route53.TxtRecord(this, 'SESVerificationRecord', {
  zone,
  recordName: `_amazonses.example.com`,
  values: [verifyDomainIdentity.getResponseField('VerificationToken')]
});

Sources: packages/@aws-cdk/custom-resources/README.md:300-314

Physical Resource ID

The physical ID is crucial for CloudFormation to track the resource. AwsCustomResource provides two main ways to define it:

PhysicalResourceId.of(id): Use a static, custom-defined ID.
PhysicalResourceId.fromResponse(path): Extract the ID from the API call's response data using a dot-notation path (e.g., Items.0.Title.S).

A PhysicalResourceIdReference can be used in onUpdate or onDelete parameters to pass the current physical resource ID to the API call.

Sources: packages/@aws-cdk/custom-resources/README.md:237-252, packages/@aws-cdk/custom-resources/test/aws-custom-resource/aws-custom-resource.test.ts:153-159

Policy and Permissions

Permissions for the API calls are managed via the policy property.

AwsCustomResourcePolicy.fromSdkCalls({ resources: [...] }): Automatically generates IAM policies based on the service and action of the calls. You must specify the resource ARNs or use AwsCustomResourcePolicy.ANY_RESOURCE.
AwsCustomResourcePolicy.fromStatements([...]): Provide your own iam.PolicyStatement objects for fine-grained control.

The construct also implements iam.IGrantable, so permissions can be added using methods like grantPassRole.

Sources: packages/@aws-cdk/custom-resources/README.md:213-227, packages/@aws-cdk/custom-resources/test/aws-custom-resource/aws-custom-resource.test.ts:89-106

Error Handling and Output

Error Handling: By default, any API error causes the resource operation to fail. The ignoreErrorCodesMatching property allows specific errors to be ignored, treating the operation as a success. However, when an error is ignored, the response data is empty, which means getResponseField and PhysicalResourceId.fromResponse cannot be used.
Output Restriction: CloudFormation limits custom resource responses to 4096 bytes. If an API call returns a large object, use the outputPaths property to select only the necessary fields to include in the response.

Sources: packages/@aws-cdk/custom-resources/README.md:254-269, packages/@aws-cdk/custom-resources/README.md:286-298

Customizing the Lambda Function

The underlying singleton Lambda function can be customized using the following properties on the AwsCustomResource construct:

Property	Type	Default	Description
`role`	`iam.IRole`	A new role is created.	An existing IAM role to use for the Lambda function.
`timeout`	`cdk.Duration`	2 minutes	The timeout for the Lambda function.
`logRetention`	`logs.RetentionDays`	`INFINITE`	How long to retain the Lambda function's logs.
`functionName`	`string`	CloudFormation-generated.	A specific name for the Lambda function.
`installLatestAwsSdk`	`boolean`	`true`	Whether to install the latest AWS SDK v2 in the Lambda. Set to `false` to optimize for speed.

Sources: packages/@aws-cdk/custom-resources/README.md:271-284, packages/@aws-cdk/custom-resources/test/aws-custom-resource/aws-custom-resource.test.ts:358-372

Summary

Sources: packages/@aws-cdk/custom-resources/README.md:5-10, 195-201

Using Custom Resources

Provider Framework

Architecture

Handlers

onEvent Handler

isComplete Handler (Asynchronous Providers)

Custom Resources for AWS APIs (AwsCustomResource)

Core Concepts

API Call Definition

Example: Verifying a Domain with SES

Physical Resource ID

Policy and Permissions

Error Handling and Output

Customizing the Lambda Function

Summary

Provider Framework

Architecture

Handlers

onEvent Handler

isComplete Handler (Asynchronous Providers)

Custom Resources for AWS APIs (AwsCustomResource)

Core Concepts

API Call Definition

Example: Verifying a Domain with SES

Physical Resource ID

Policy and Permissions

Error Handling and Output

Customizing the Lambda Function

Summary

Using Custom Resources

Provider Framework

Architecture

Handlers

onEvent Handler

isComplete Handler (Asynchronous Providers)

Custom Resources for AWS APIs (AwsCustomResource)

Core Concepts

API Call Definition

Example: Verifying a Domain with SES

Physical Resource ID

Policy and Permissions

Error Handling and Output

Customizing the Lambda Function

Summary

Provider Framework

Architecture

Handlers

onEvent Handler

isComplete Handler (Asynchronous Providers)

Custom Resources for AWS APIs (AwsCustomResource)

Core Concepts

API Call Definition

Example: Verifying a Domain with SES

Physical Resource ID

Policy and Permissions

Error Handling and Output

Customizing the Lambda Function

Summary

`onEvent` Handler

`isComplete` Handler (Asynchronous Providers)

Custom Resources for AWS APIs (`AwsCustomResource`)

`onEvent` Handler

`isComplete` Handler (Asynchronous Providers)

Custom Resources for AWS APIs (`AwsCustomResource`)

`onEvent` Handler

`isComplete` Handler (Asynchronous Providers)

Custom Resources for AWS APIs (`AwsCustomResource`)

`onEvent` Handler

`isComplete` Handler (Asynchronous Providers)

Custom Resources for AWS APIs (`AwsCustomResource`)