@aws-cdk/custom-resources¶
CDK Custom Resources¶
Custom Resources are CloudFormation resources that are implemented by arbitrary user code. They can do arbitrary lookups or modifications during a CloudFormation synthesis run.
You will typically use Lambda to implement a Construct implemented as a
Custom Resource (though SNS topics can be used as well). Your Lambda function
will be sent a CREATE
, UPDATE
or DELETE
message, depending on the
CloudFormation life cycle, and can return any number of output values which
will be available as attributes of your Construct. In turn, those can
be used as input to other Constructs in your model.
In general, consumers of your Construct will not need to care whether it is implemented in term of other CloudFormation resources or as a custom resource.
Note: when implementing your Custom Resource using a Lambda, use
a SingletonLambda
so that even if your custom resource is instantiated
multiple times, the Lambda will only get uploaded once.
Example¶
Sample of a Custom Resource that copies files into an S3 bucket during deployment
(implementation of actual copy.py
operation elided).
interface CopyOperationProps {
sourceBucket: IBucket;
targetBucket: IBucket;
}
class CopyOperation extends Construct {
constructor(parent: Construct, name: string, props: DemoResourceProps) {
super(parent, name);
const lambdaProvider = new SingletonLambda(this, 'Provider', {
uuid: 'f7d4f730-4ee1-11e8-9c2d-fa7ae01bbebc',
code: new LambdaInlineCode(resources['copy.py']),
handler: 'index.handler',
timeout: 60,
runtime: LambdaRuntime.Python3,
});
new CustomResource(this, 'Resource', {
lambdaProvider,
properties: {
sourceBucketArn: props.sourceBucket.bucketArn,
targetBucketArn: props.targetBucket.bucketArn,
}
});
}
}
More examples are in the example
directory, including an example of how to use
the cfnresponse
module that is provided for you by CloudFormation.
References¶
See the following section of the docs on details to write Custom Resources:
Reference¶
CustomResource¶
-
class
_aws-cdk_custom-resources.
CustomResource
(parent, name, props)¶ Custom resource that is implemented using a Lambda As a custom resource author, you should be publishing a subclass of this class that hides the choice of provider, and accepts a strongly-typed properties object with the properties your provider accepts.
Extends: CustomResource
Parameters: - parent (
Construct
) – - name (string) –
- props (
CustomResourceProps
) –
-
renderProperties
() → string => any¶ Override renderProperties to mix in the user-defined properties
Return type: any
- parent (
CustomResourceProps (interface)¶
-
class
_aws-cdk_custom-resources.
CustomResourceProps
¶ Properties to provide a Lambda-backed custom resource
-
lambdaProvider
¶ The Lambda provider that implements this custom resource. We recommend using a SingletonLambda for this. Optional, exactly one of lamdaProvider or topicProvider must be set.
Type: LambdaRef
or None
-
topicProvider
¶ The SNS Topic for the provider that implements this custom resource. Optional, exactly one of lamdaProvider or topicProvider must be set.
Type: TopicRef
or None
-
properties
¶ Properties to pass to the Lambda
Type: any or None
-
SingletonLambda¶
-
class
_aws-cdk_custom-resources.
SingletonLambda
(parent, name, props)¶ A Lambda that will only ever be added to a stack once. The lambda is identified using the value of ‘uuid’. Run ‘uuidgen’ for every SingletonLambda you create.
Extends: LambdaRef
Parameters: - parent (
Construct
) – - name (string) –
- props (
SingletonLambdaProps
) –
-
addPermission
(name, permission)¶ Adds a permission to the Lambda resource policy.
Parameters: - name (string) –
- permission (
LambdaPermission
) –
-
functionName
¶ The name of the function.
Type: FunctionName
-
functionArn
¶ The ARN fo the function.
Type: FunctionArn
-
role
¶ The IAM role associated with this function.
Type: Role
or None
-
canCreatePermissions
¶ Whether the addPermission() call adds any permissions True for new Lambdas, false for imported Lambdas (they might live in different accounts).
Type: boolean
- parent (