cloudformation.rst

AWS CloudFormation Library

The :doc:`AWS Construct Library <aws-construct-lib>` includes constructs with rich APIs for defining AWS infrastructure. For example, the :py:class:`@aws-cdk/aws-s3.Bucket` construct can be used to define S3 Buckets, the :py:class:`@aws-cdk/aws-sns.Topic` construct can be used to define SNS Topics, etc.

Under the hood, these constructs are implemented using CloudFormation resources, which are available under the CfnXxx classes in each library. For example, the :py:class:`@aws-cdk/aws-s3.Bucket` construct uses the :py:class:`@aws-cdk/aws-s3.CfnBucket` resource (as well as other resources, depending on what bucket APIs are used).

Important

Generally, when building CDK apps, you shouldn't need to interact with CloudFormation directly. However, there might be advanced use cases and migration scenarios where this might be required. We are also aware that there might be gaps in capabilities in the AWS Construct Library over time.

Resources

CloudFormation resource classes are automatically generated from the AWS CloudFormation Resource Specification and available under the CfnXxx classes of each AWS library. Their API matches 1:1 with how you would use these resources in CloudFormation.

When defining CloudFormation resource, the props argument of the class initializer will match 1:1 to the resource's properties in CloudFormation.

For example, to define an AWS::SQS::Queue resource encrypted with an AWS managed key you can directly specify the KmsMasterKeyId property.

import sqs = require('@aws-cdk/aws-sqs');

new sqs.CfnQueue(this, 'MyQueueResource', {
    kmsMasterKeyId: 'alias/aws/sqs'
});

For reference, if you use the :py:class:`@aws-cdk/aws-sqs.Queue` construct, you can define managed queue encryption as follows:

import sqs = require('@aws-cdk/aws-sqs');

new sqs.Queue(this, 'MyQueue', {
    encryption: sqs.QueueEncryption.KmsManaged
});

Resource Attributes

To reference the runtime attributes of CloudFormation resources, use one of the properties available on the resource object.

The following example configures a |LAM| function's dead letter queue to use the ARN of an |SQS| queue resource.

import sqs = require('@aws-cdk/aws-sqs');
import lambda = require('@aws-cdk/aws-lambda');

const dlq = new sqs.CfnQueue(this, { name: 'DLQ' });

new lambda.CfnFunction(this, {
   deadLetterConfig: {
      targetArn: dlq.queueArn
   }
});

The :py:attr:`@aws-cdk/cdk.Resource.ref` attribute represents the |cfn| resource's intrinsic reference (or "Return Value"). For example, for dlq.ref will also refer to the queue's ARN. When possible, it is preferrable to use an explicitly named attribute instead of ref.

Resource Options

The :py:attr:`@aws-cdk/cdk.Resource.options` object includes |CFN| options, such as condition, updatePolicy, createPolicy and metadata, for a resource.

Parameters

import sns = require('@aws-cdk/aws-sns');
import cdk = require('@aws-cdk/cdk');

const p = new cdk.Parameter(this, 'MyParam', { type: 'String' });
new sns.CfnTopic(this, 'MyTopic', { displayName: p.ref });

Outputs

import sqs = require('@aws-cdk/aws-sqs');
import cdk = require('@aws-cdk/cdk');

const queue = new sqs.CfnQueue(this, 'MyQueue');
const out = new cdk.Output(this, 'MyQueueArn', { value: queue.queueArn });

const import = out.makeImportValue();
assert(import === { "Fn::ImportValue": out.exportName }

Conditions

import sqs = require('@aws-cdk/aws-sqs');
import cdk = require('@aws-cdk/cdk');
const cond = new cdk.Condition(this, 'MyCondition', {
    expression: new cdk.FnIf(...)
});

const queue = new sqs.CfnQueue(this, 'MyQueue');
queue.options.condition = cond;

Intrinsic Functions

import { Fn } from'@aws-cdk/cdk';
Fn.join(",", [...])

Pseudo Parameters

import cdk = require('@aws-cdk/cdk');
new cdk.AwsRegion()