class CustomResource (construct)

Language	Type name
.NET	Amazon.CDK.CustomResource
Go	github.com/aws/aws-cdk-go/awscdk/v2#CustomResource
Java	software.amazon.awscdk.CustomResource
Python	aws_cdk.CustomResource
TypeScript (source)	aws-cdk-lib » CustomResource

Implements IConstruct, IDependable, IResource, IEnvironmentAware

Instantiation of a custom resource, whose implementation is provided a Provider.

This class is intended to be used by construct library authors. Application builder should not be able to tell whether or not a construct is backed by a custom resource, and so the use of this class should be invisible.

Instead, construct library authors declare a custom construct that hides the choice of provider, and accepts a strongly-typed properties object with the properties your provider accepts.

Your custom resource provider (identified by the serviceToken property) can be one of 4 constructs:

• If you are authoring a construct library or application, we recommend you use the Provider class in the custom-resources module.
• If you are authoring a construct for the CDK's AWS Construct Library, you should use the CustomResourceProvider construct in this package.
• If you want full control over the provider, you can always directly use a Lambda Function or SNS Topic by passing the ARN into serviceToken.

Example

const stack = new Stack();
const durToken = new CfnParameter(stack, 'MyParameter', {
  type: 'Number',
  default: 60,
});
new CustomResource(stack, 'MyCustomResource', {
  serviceToken: 'MyServiceToken',
  serviceTimeout: Duration.seconds(durToken.valueAsNumber),
});

Initializer

new CustomResource(scope: Construct, id: string, props: CustomResourceProps)

Parameters

• scope Construct
• id string
• props CustomResourceProps

Construct Props

Name	Type	Description
serviceToken	string	The ARN of the provider which implements this custom resource type.
pascalCaseProperties?	boolean	Convert all property keys to pascal case.
properties?	{ [string]: any }	Properties to pass to the Lambda.
removalPolicy?	RemovalPolicy	The policy to apply when this resource is removed from the application.
resourceType?	string	For custom resources, you can specify AWS::CloudFormation::CustomResource (the default) as the resource type, or you can specify your own resource type name.
serviceTimeout?	Duration	The maximum time that can elapse before a custom resource operation times out.

---

serviceToken

Type: string

The ARN of the provider which implements this custom resource type.

You can implement a provider by listening to raw AWS CloudFormation events and specify the ARN of an SNS topic (topic.topicArn) or the ARN of an AWS Lambda function (lambda.functionArn) or use the CDK's custom resource provider framework which makes it easier to implement robust providers.

Provider framework:

// use the provider framework from aws-cdk/custom-resources:
const provider = new customresources.Provider(this, 'ResourceProvider', {
  onEventHandler,
  isCompleteHandler, // optional
});

new CustomResource(this, 'MyResource', {
  serviceToken: provider.serviceToken,
});

AWS Lambda function (not recommended to use AWS Lambda Functions directly, see the module README):

// invoke an AWS Lambda function when a lifecycle event occurs:
new CustomResource(this, 'MyResource', {
  serviceToken: myFunction.functionArn,
});

SNS topic (not recommended to use AWS Lambda Functions directly, see the module README):

// publish lifecycle events to an SNS topic:
new CustomResource(this, 'MyResource', {
  serviceToken: myTopic.topicArn,
});

Maps to ServiceToken property for the AWS::CloudFormation::CustomResource resource

---

pascalCaseProperties?

Type: boolean (optional, default: false)

Convert all property keys to pascal case.

---

properties?

Type: { [string]: any } (optional, default: No properties.)

Properties to pass to the Lambda.

Values in this properties dictionary can possibly overwrite other values in CustomResourceProps E.g. ServiceToken and ServiceTimeout It is recommended to avoid using same keys that exist in CustomResourceProps

---

removalPolicy?

Type: RemovalPolicy (optional, default: cdk.RemovalPolicy.Destroy)

The policy to apply when this resource is removed from the application.

---

resourceType?

Type: string (optional, default: AWS::CloudFormation::CustomResource)

For custom resources, you can specify AWS::CloudFormation::CustomResource (the default) as the resource type, or you can specify your own resource type name.

For example, you can use "Custom::MyCustomResourceTypeName".

Custom resource type names must begin with "Custom::" and can include alphanumeric characters and the following characters: _@-. You can specify a custom resource type name up to a maximum length of 60 characters. You cannot change the type during an update.

Using your own resource type names helps you quickly differentiate the types of custom resources in your stack. For example, if you had two custom resources that conduct two different ping tests, you could name their type as Custom::PingTester to make them easily identifiable as ping testers (instead of using AWS::CloudFormation::CustomResource).

See also: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cfn-customresource.html#aws-cfn-resource-type-name

---

serviceTimeout?

Type: Duration (optional, default: Duration.seconds(3600))

The maximum time that can elapse before a custom resource operation times out.

The value must be between 1 second and 3600 seconds.

Maps to ServiceTimeout property for the AWS::CloudFormation::CustomResource resource

A token can be specified for this property, but it must be specified with Duration.seconds(). Example

const stack = new Stack();
const durToken = new CfnParameter(stack, 'MyParameter', {
  type: 'Number',
  default: 60,
});
new CustomResource(stack, 'MyCustomResource', {
  serviceToken: 'MyServiceToken',
  serviceTimeout: Duration.seconds(durToken.valueAsNumber),
});

Properties

Name	Type	Description
env	ResourceEnvironment	The environment this resource belongs to.
node	Node	The tree node.
ref	string	The physical name of this custom resource.
stack	Stack	The stack in which this resource is defined.
static PROPERTY_INJECTION_ID	string	Uniquely identifies this class.

---

env

Type: ResourceEnvironment

The environment this resource belongs to.

For resources that are created and managed in a Stack (those created by creating new class instances like new Role(), new Bucket(), etc.), this is always the same as the environment of the stack they belong to.

For referenced resources (those obtained from referencing methods like Role.fromRoleArn(), Bucket.fromBucketName(), etc.), they might be different than the stack they were imported into.

---

node

Type: Node

The tree node.

---

ref

Type: string

The physical name of this custom resource.

---

stack

Type: Stack

The stack in which this resource is defined.

---

static PROPERTY_INJECTION_ID

Type: string

Uniquely identifies this class.

Methods

Name	Description
applyRemovalPolicy(policy)	Apply the given removal policy to this resource.
getAtt(attributeName)	Returns the value of an attribute of the custom resource of an arbitrary type.
getAttString(attributeName)	Returns the value of an attribute of the custom resource of type string.
toString()	Returns a string representation of this construct.

---

applyRemovalPolicy(policy)

public applyRemovalPolicy(policy: RemovalPolicy): void

Parameters

• policy RemovalPolicy

Apply the given removal policy to this resource.

The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.

The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN).

---

getAtt(attributeName)

public getAtt(attributeName: string): Reference

Parameters

• attributeName string — the name of the attribute.

Returns

• Reference

Returns the value of an attribute of the custom resource of an arbitrary type.

Attributes are returned from the custom resource provider through the Data map where the key is the attribute name.

---

getAttString(attributeName)

public getAttString(attributeName: string): string

Parameters

• attributeName string — the name of the attribute.

Returns

• string

Returns the value of an attribute of the custom resource of type string.

Attributes are returned from the custom resource provider through the Data map where the key is the attribute name.

---

toString()

public toString(): string

Returns

• string

Returns a string representation of this construct.