@aws-cdk/aws-cloudformation

CDK Constructs for AWS CloudFormation

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

CodePipeline Actions for CloudFormation

This module contains Actions that allows you to deploy to CloudFormation from AWS CodePipeline.

For example, the following code fragment defines a pipeline that automatically deploys a CloudFormation template directly from a CodeCommit repository, with a manual approval step in between to confirm the changes:

example Pipeline to deploy CloudFormation

See the AWS documentation for more details about using CloudFormation in CodePipeline.

Actions defined by this package

This package defines the following actions:

• PipelineCreateUpdateStackAction - Deploy a CloudFormation template directly from the pipeline. The indicated stack is created, or updated if it already exists. If the stack is in a failure state, deployment will fail (unless replaceOnFailure is set to true, in which case it will be destroyed and recreated).
• PipelineDeleteStackAction - Delete the stack with the given name.
• PipelineCreateReplaceChangeSetAction - Prepare a change set to be applied later. You will typically use change sets if you want to manually verify the changes that are being staged, or if you want to separate the people (or system) preparing the changes from the people (or system) applying the changes.
• PipelineExecuteChangeSetAction - Execute a change set prepared previously.

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.26.0 (2019-03-20)

Bug Fixes

• aws-cdk: fix VpcNetwork.importFromContext() (#2008) (e1a1a7b), closes #1998
• aws-cdk: update F# template to latest CDK version (#2006) (bda12f2)
• cdk: merge cloudFormation tags with aspect tags (#1762) (bfb14b6), closes #1725
• cfn2ts: properly de-Tokenize L1 string-arrays (#2033) (1e50383), closes #2030
• core: allow embedding condition expression as strings (#2007) (6afa87f), closes #1984
• ecs: make TaskDefinition accept IRoles (#2034) (f32431a), closes #1925
• lambda: expose underlying function's role on the alias (#2024) (de296de)
• stepfunctions: Actually perform rendering of NotCondition (06b59d9)
• toolkit: 'cdk deploy' support updates to Outputs (#2029) (23509ae), closes #778
• toolkit: increase number of retries (#2053) (133dc98), closes #1647
• rename core classes adding a Cfn prefix (#1960) (5886bf6), closes #1462 #288

Code Refactoring

• name "toCloudFormation" internal (renamed to _toCloudFormation) (#2047) (515868b), closes #2044 #2016

Features

• aws-cdk: support fixed repository name for DockerImageAsset (#2032) (942f938)
• aws-rds: ability to add an existing security group to RDS cluster (#2021) (1f24336)
• cfn2ts: make cfn2ts output TSDoc-compatible docblocks (#2000) (c6c66e9)
• cfnspec: update to version 2.28.0 (#2035) (6a671f2)
• cloudformation: allow specifying additional inputs for deploy Actions (#2020) (2d463be), closes #1247
• core: can use Constructs to model applications (#1940) (32c2377), closes #1479
• ecs: support private registry authentication (#1737) (11ed691), closes #1698
• glue: add L2 resources for Database and Table (#1988) (3117cd3)
• region-info: Model region-specific information (#1839) (946b444), closes #1282
• servicediscovery: AWS Cloud Map construct library (#1804) (1187366)
• ses: add constructs for email receiving (#1971) (3790858)
• add more directories excluded and treated as source in the JetBrains script. (#1961) (a1df717)

BREAKING CHANGES TO EXPERIMENTAL FEATURES

• “toCloudFormation” is now internal and should not be called directly. Instead use “app.synthesizeStack”
• ecs: ContainerImage.fromDockerHub has been renamed to ContainerImage.fromRegistry.
• rename Condition to CfnCondition.
• rename StackElement to CfnElement.
• rename Parameter to CfnParameter.
• rename Resource to CfnResource.
• rename Output to CfnOutput.
• rename Mapping to CfnMapping.
• rename Referenceable to CfnRefElement.
• rename IConditionExpression to ICfnConditionExpression.
• rename CfnReference to Reference.
• rename Rule to CfnRule.