CDK Constructs for AWS CloudFormation
Project description
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', {
provider: CustomResourceProvider.lambda(provider),
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:
AWS Custom Resource
Sometimes a single API call can fill the gap in the CloudFormation coverage. In
this case you can use the AwsCustomResource
construct. This construct creates
a custom resource that can be customized to make specific API calls for the
CREATE
, UPDATE
and DELETE
events. Additionally, data returned by the API
call can be extracted and used in other constructs/resources (creating a real
CloudFormation dependency using Fn::GetAtt
under the hood).
The physical id of the custom resource can be specified or derived from the data return by the API call.
The AwsCustomResource
uses the AWS SDK for JavaScript. Services, actions and
parameters can be found in the API documentation.
Path to data must be specified using a dot notation, e.g. to get the string value
of the Title
attribute for the first item returned by dynamodb.query
it should
be Items.0.Title.S
.
Examples
Verify a domain with SES:
const verifyDomainIdentity = new AwsCustomResource(this, 'VerifyDomainIdentity', {
onCreate: {
service: 'SES',
action: 'verifyDomainIdentity',
parameters: {
Domain: 'example.com'
},
physicalResourceIdPath: 'VerificationToken' // Use the token returned by the call as physical id
}
});
new route53.TxtRecord(zone, 'SESVerificationRecord', {
recordName: `_amazonses.example.com`,
recordValue: verifyDomainIdentity.getData('VerificationToken')
});
Get the latest version of a secure SSM parameter:
const getParameter = new AwsCustomResource(this, 'GetParameter', {
onUpdate: { // will also be called for a CREATE event
service: 'SSM',
action: 'getParameter',
parameters: {
Name: 'my-parameter',
WithDecryption: true
},
physicalResourceId: Date.now().toString() // Update physical id to always fetch the latest version
}
});
// Use the value in another construct with
getParameter.getData('Parameter.Value')
IAM policy statements required to make the API calls are derived from the calls
and allow by default the actions to be made on all resources (*
). You can
restrict the permissions by specifying your own list of statements with the
policyStatements
prop.
Chained API calls can be achieved by creating dependencies:
const awsCustom1 = new AwsCustomResource(this, 'API1', {
onCreate: {
service: '...',
action: '...',
physicalResourceId: '...'
}
});
const awsCustom2 = new AwsCustomResource(this, 'API2', {
onCreate: {
service: '...',
action: '...'
parameters: {
text: awsCustom1.getData('Items.0.text')
},
physicalResourceId: '...'
}
})
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for aws-cdk.aws-cloudformation-0.33.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | b083a2f39e2ba64fdb1013cb5cd800471b23c94c22dea12a5a7878de36b4106d |
|
MD5 | b3bc461b1183cc89f28a14fb4013d361 |
|
BLAKE2b-256 | 9ea04566860adc6b38408cbc9464022e4d004ee9002e95ac768bb1ab40266361 |
Hashes for aws_cdk.aws_cloudformation-0.33.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f3e37a2eca49f75025277422048d8106d45e7a2589dd3cb26113f20fa145d0d0 |
|
MD5 | 32b4306de36e76712526e90e5501e233 |
|
BLAKE2b-256 | ed7f6f57ff7bc5c251be68421acf0f27ba19ffd4162c829b43373b044f799b71 |