This documentation is for the developer preview release of the AWS CDK. Do not use this version of the AWS CDK in production. Subsequent releases of the AWS CDK will likely include breaking changes.

AWS CloudFormation Library

The AWS Construct Library includes constructs with rich APIs for defining AWS infrastructure. For example, the @aws-cdk/aws-s3.Bucket construct can be used to define S3 Buckets, the @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 @aws-cdk/aws-s3.Bucket construct uses the @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 @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 Lambda function’s dead letter queue to use the ARN of an Amazon 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 @aws-cdk/cdk.Resource.ref attribute represents the AWS CloudFormation 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 @aws-cdk/cdk.Resource.options object includes AWS CloudFormation 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

cdk.Condition can be used to define CloudFormation “Condition” elements in the template. The cdk.Fn.conditionXx() static methods can be used to produce “condition expressions”.

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

const param = new cdk.Parameter(this, 'Param1', { type: 'String' });
const cond1 = new cdk.Condition(this, 'Condition1', { expression: cdk.Fn.conditionEquals("a", "b") });
const cond2 = new cdk.Condition(this, 'Condition2', { expression: cdk.Fn.conditionContains([ "a", "b", "c" ], "c") });
const cond3 = new cdk.Condition(this, 'Condition3', { expression: cdk.Fn.conditionEquals(param, "hello") });

const cond4 = new cdk.Condition(this, 'Condition4', {
  expression: cdk.Fn.conditionOr(cond1, cond2, cdk.Fn.conditionNot(cond3))
});

const cond = new cdk.Condition(this, 'MyCondition', {
    expression: new cdk.FnIf(...)
});

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

Intrinsic Functions

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

Pseudo Parameters

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