@aws-cdk/aws-cloudformation

CDK Constructs for AWS CloudFormation

This module is part of the AWS Cloud Development Kit project.

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:

• Introduction
• Reference
• Code Reference

Changelog

0.28.0 (2019-04-04)

Bug Fixes

• aws-ecs: use executionRole for event rule target (#2165) (aa6f7bc), closes #2015

• core: remove cdk.Secret (#2068) (b53d04d), closes #2064

• feat(aws-iam): refactor grants, add OrganizationPrincipal (#1623) (1bb8ca9), closes #1623 #236

Code Refactoring

• cdk: introduce SecretValue to represent secrets (#2161) (a3d9f2e)

Features

• codepipeline: move all of the Pipeline Actions to their dedicated package. (#2098) (b314ecf)
• codepipeline: re-factor the CodePipeline Action bind method to take a Role separately from the Pipeline. (#2085) (ffe0046)
• ec2: support reserving IP space in VPCs (#2090) (4819ff4)
• Add python support to cdk init (#2130) (997dbcc)
• ecs: support AWS Cloud Map (service discovery) (#2065) (4864cc8), closes #1554
• lambda: add a newVersion method. (#2099) (6fc179a)
• update CloudFormation resource spec to v2.29.0 (#2170) (ebc490d)

BREAKING CHANGES TO EXPERIMENTAL FEATURES

• The secretsmanager.SecretString class has been removed in favor of cdk.SecretValue.secretsManager(id[, options])
• The following prop types have been changed from string to cdk.SecretValue: codepipeline-actions.AlexaSkillDeployAction.clientSecret, codepipeline-actions.AlexaSkillDeployAction.refreshToken, codepipeline-actions.GitHubSourceAction.oauthToken, iam.User.password
• secretsmanager.Secret.stringValue and jsonFieldValue have been removed. Use secretsmanage.Secret.secretValue and secretJsonValue instead.
• secretsmanager.Secret.secretString have been removed. Use cdk.SecretValue.secretsManager() or secretsmanager.Secret.import(..).secretValue.
• The class cdk.Secret has been removed. Use cdk.SecretValue instead.
• The class cdk.DynamicReference is no longer a construct, and it's constructor signature was changed and was renamed cdk.CfnDynamicReference.
• grant(function.role) and grant(project.role) are now grant(function) and grant(role).
• core: Replace use of cdk.Secret with secretsmanager.SecretString (preferred) or ssm.ParameterStoreSecureString.
• codepipeline: this changes the package of all CodePipeline Actions to be aws-codepipeline-actions.
• codepipeline: this moves all classes from the aws-codepipeline-api package to the aws-codepipeline package.
• codepipeline: this changes the CodePipeline Action naming scheme from <service>.Pipeline<Category>Action (s3.PipelineSourceAction) to codepipeline_actions.<Service><Category>Action (codepipeline_actions.S3SourceAction).