Skip to content

Latest commit

 

History

History
1570 lines (1269 loc) · 73.4 KB

CHANGELOG.md

File metadata and controls

1570 lines (1269 loc) · 73.4 KB
Raw

[UNRELEASED]

CloudFormation Changes

0.9.2 (2018-09-20)

NOTICE: This release includes a framework-wide breaking change which changes the type of all the string resource attributes across the framework. Instead of using strong-types that extend cdk.Token (such as QueueArn, TopicName, etc), we now represent all these attributes as normal strings, and codify the tokens into the string (using the feature introduced in #168).

Furthermore, the cdk.Arn type has been removed. In order to format/parse ARNs, use the static methods on cdk.ArnUtils.

See motivation and discussion in #695.

Breaking Changes

  • cfn2ts: use stringified tokens for resource attributes instead of strong types (#712) (6508f78), closes #518 #695 #744
  • aws-dynamodb: Attribute type for keys, changes the signature of the addPartitionKey and addSortKey methods to be consistent across the board. (#720) (e6cc189)
  • aws-codebuild: fix typo "priviledged" -> "privileged

Bug Fixes

Features

  • aws-apigateway: new API Gateway Construct Library (#665) (b0f3857)
  • aws-cdk: detect presence of EC2 credentials (#724) (8e8c295), closes #702 #130
  • aws-codepipeline: make the Stage insertion API in CodePipeline more flexible (#460) (d182818)
  • aws-codepipeline: new "Pipeline#addStage" convenience method (#647) (25c9fa0)
  • aws-rds: add support for parameter groups (#729) (2541508), closes #719
  • docs: add documentation for CDK toolkit plugings (#733) (965b918)
  • dependencies: upgrade to jsii 0.7.6

0.9.1 (2018-09-13)

Bug Fixes

  • aws-cdk: Fix proxy support for account lookup (#693) (5468225), closes #645

Features

  • aws-ec2 BREAKING: Move LoadBalancer to aws-elasticloadbalancing package (#705) (4bd1cf2)
  • aws-serverless BREAKING: Rename @aws-cdk/aws-serverless to @aws-cdk/aws-sam (#704) (3a67d5d)
  • aws-dynamodb: Support DynamoDB TTL (#691) (35b6206)
  • aws-dynamodb: Support DynamoDB PITR (#701) (7a4d7b7)
  • aws-ecr: Add support for ECR repositories (#697) (c6c09bf)
  • aws-lambda: Add support for XRay Tracing (#675) (b4435cc)
  • cfnspec: Add DeploymentPreference Patch for SAM Spec (#681) (#681) (f96c487)

0.9.0 -- 2018-09-10

The headliners of this release are .NET support, and a wealth of commits by external contributors who are stepping up to fix the CDK for their use cases! Thanks all for the effort put into this release!

Features

  • Add strongly-named .NET targets, and a cdk init template for C# projects (@mpiroc in #617, #643).
  • @aws-cdk/aws-autoscaling: Allow attaching additional security groups to Launch Configuration (@moofish32 in #636).
  • @aws-cdk/aws-autoscaling: Support update and creation policies on AutoScalingGroups (@rix0rrr in #595).
  • @aws-cdk/aws-codebuild: Add support for running script from an asset (@rix0rrr in #677).
  • @aws-cdk/aws-codebuild: New method addBuildToPipeline on Project (@skinny85 in 783dcb3).
  • @aws-cdk/aws-codecommit: New method addToPipeline on Repository (@skinny85 in #616).
  • @aws-cdk/aws-codedeploy: Add initial support for CodeDeploy (@skinny85 in #593, #641).
  • @aws-cdk/aws-dynamodb: Add support for DynamoDB autoscaling (@SeekerWing in #637).
  • @aws-cdk/aws-dynamodb: Add support for DynamoDB streams (@rhboyd in #633).
  • @aws-cdk/aws-dynamodb: Add support for server-side encryption (@jungseoklee in #684).
  • @aws-cdk/aws-ec2 (BREAKING): SecurityGroup can now be used as a Connectable #582).
  • @aws-cdk/aws-ec2: Add VPC tagging ([@moofish] in #538).
  • @aws-cdk/aws-ec2: Add support for InstanceSize.Nano (@rix0rrr in #581)
  • @aws-cdk/aws-lambda: Add support for dead letter queues (@SeekerWing in #663).
  • @aws-cdk/aws-lambda: Add support for placing a Lambda in a VPC (@rix0rrr in #598).
  • @aws-cdk/aws-logs: Add extractMetric() helper function (@rix0rrr in #676).
  • @aws-cdk/aws-rds: Add support for Aurora PostreSQL/MySQL engines (@cookejames in #586)
  • @aws-cdk/aws-s3: Additional grant methods for Buckets (@eladb in #591)
  • @aws-cdk/aws-s3: New method addToPipeline on Bucket (@skinny85 in c8b7a49).
  • aws-cdk: Add support for HTTP proxies (@rix0rrr in #666).
  • aws-cdk: Toolkit now shows failure reason if stack update fails (@rix0rrr in #609).
  • cdk-build-tools: Add support for running experiment JSII versions (@RomainMuller in #649).

Changes

  • BREAKING: Generate classes and types for the CloudFormation resource .ref attributes (@rix0rrr in #627).
  • BREAKING: Make types accepted in Policy-related classes narrower (from any to Arn, for example) to reduce typing mistakes (@rix0rrr in #629).
  • @aws-cdk/aws-codepipeline (BREAKING): Align the CodePipeline APIs (@skinny85 in #492, #568)
  • @aws-cdk/aws-ec2 (BREAKING): Move Fleet/AutoScalingGroup to its own package (@rix0rrr in #608).
  • aws-cdk: Simplify plugin protocol (@RomainMuller in #646).

Bug Fixes

  • @aws-cdk/aws-cloudfront: Fix CloudFront behavior for ViewerProtocolPolicy (@mindstorms6 in #615).
  • @aws-cdk/aws-ec2: VPC Placement now supports picking Isolated subnets (@rix0rrr in #610).
  • @aws-cdk/aws-logs: Add export()/import() capabilities (@rix0rrr in #630).
  • @aws-cdk/aws-rds: Fix a bug where a cluster with 1 instance could not be created (@cookejames in #578)
  • @aws-cdk/aws-s3: Bucket notifications can now add dependencies, fixing creation order (@eladb in #584).
  • @aws-cdk/aws-s3: Remove useless bucket name validation (@rix0rrr in #628).
  • @aws-cdk/aws-sqs: Make QueueRef.encryptionMasterKey readonly (@RomainMuller in #650).
  • assets: S3 read permissions are granted on a prefix to fix lost permissions during asset update (@rix0rrr in #510).
  • aws-cdk: Remove bootstrapping error if multiple stacks are in the same environment (@RomainMuller in #625).
  • aws-cdk: Report and continue if git throws errors during cdk init (@rix0rrr in #587).

CloudFormation Changes

  • @aws-cdk/cfnspec: Updated CloudFormation resource specification to v2.6.0 (@RomainMuller in #594)

    • New AWS Construct Library
      • @aws-cdk/aws-sagemaker supports AWS::SageMaker resources
    • New Resource Types
      • AWS::AmazonMQ::Broker
      • AWS::AmazonMQ::Configuration
      • AWS::CodePipeline::Webhook
      • AWS::Config::AggregationAuthorization
      • AWS::Config::ConfigurationAggregator
      • AWS::EC2::VPCEndpointConnectionNotification
      • AWS::EC2::VPCEndpointServicePermissions
      • AWS::IAM::ServiceLinkedRole
      • AWS::SSM::ResourceDataSync
      • AWS::SageMaker::Endpoint
      • AWS::SageMaker::EndpointConfig
      • AWS::SageMaker::Model
      • AWS::SageMaker::NotebookInstance
      • AWS::SageMaker::NotebookInstanceLifecycleConfig
    • Attribute Changes
      • AWS::CodePipeline::Pipeline Version (added)
    • Property Changes
      • AWS::AppSync::DataSource HttpConfig (added)
      • AWS::DAX::Cluster SSESpecification (added)
      • AWS::DynamoDB::Table Stream (added)
      • AWS::DynamoDB::Table AutoScalingSupport (added)
      • AWS::EC2::VPCEndpoint IsPrivateDnsEnabled (added)
      • AWS::EC2::VPCEndpoint SecurityGroupIds (added)
      • AWS::EC2::VPCEndpoint SubnetIds (added)
      • AWS::EC2::VPCEndpoint VPCEndpointType (added)
      • AWS::EC2::VPCEndpoint RouteTableIds.DuplicatesAllowed (deleted)
      • AWS::EC2::VPCPeeringConnection PeerRegion (added)
      • AWS::EFS::FileSystem ProvisionedThroughputInMibps (added)
      • AWS::EFS::FileSystem ThroughputMode (added)
      • AWS::EMR::Cluster KerberosAttributes (added)
      • AWS::Glue::Classifier JsonClassifier (added)
      • AWS::Glue::Classifier XMLClassifier (added)
      • AWS::Glue::Crawler Configuration (added)
      • AWS::Lambda::Lambda DLQConfigurationSupport (added)
      • AWS::Neptune::DBInstance DBSubnetGroupName.UpdateType (changed)
        • Old: Mutable
        • New: Immutable
      • AWS::SNS::Subscription DeliveryPolicy (added)
      • AWS::SNS::Subscription FilterPolicy (added)
      • AWS::SNS::Subscription RawMessageDelivery (added)
      • AWS::SNS::Subscription Region (added)
      • AWS::SQS::Queue Tags (added)
      • AWS::ServiceDiscovery::Service HealthCheckCustomConfig (added)
    • Property Type Changes
      • AWS::AppSync::DataSource.HttpConfig (added)
      • AWS::DAX::Cluster.SSESpecification (added)
      • AWS::EMR::Cluster.KerberosAttributes (added)
      • AWS::Glue::Classifier.JsonClassifier (added)
      • AWS::Glue::Classifier.XMLClassifier (added)
      • AWS::ServiceDiscovery::Service.HealthCheckCustomConfig (added)
      • AWS::CloudFront::Distribution.CacheBehavior FieldLevelEncryptionId (added)
      • AWS::CloudFront::Distribution.DefaultCacheBehavior FieldLevelEncryptionId (added)
      • AWS::CodeBuild::Project.Artifacts EncryptionDisabled (added)
      • AWS::CodeBuild::Project.Artifacts OverrideArtifactName (added)
      • AWS::CodeBuild::Project.Environment Certificate (added)
      • AWS::CodeBuild::Project.Source ReportBuildStatus (added)
      • AWS::ServiceDiscovery::Service.DnsConfig RoutingPolicy (added)
      • AWS::WAF::WebACL.ActivatedRule Action.Required (changed)
        • Old: true
        • New: false

  • @aws-cdk/cfnspec: Updated Serverless Application Model (SAM) Resource Specification (@RomainMuller in #594)

    • Property Changes
      • AWS::Serverless::Api MethodSettings (added)
    • Property Type Changes
      • AWS::Serverless::Function.SQSEvent (added)
      • AWS::Serverless::Function.EventSource Properties.Types (changed)
        • Added SQSEvent

0.8.2 - 2018-08-15

Features

  • @aws-cdk/cdk: Tokens can now be transparently embedded into strings and encoded into JSON without losing their semantics. This makes it possible to treat late-bound (deploy-time) values as if they were regular strings (@rix0rrr in #518).
  • @aws-cdk/aws-s3: add support for bucket notifications to Lambda, SNS, and SQS targets (@eladb in #201, #560, #561, #564)
  • @aws-cdk/cdk: non-alphanumeric characters can now be used as construct identifiers (@eladb in #556)
  • @aws-cdk/aws-iam: add support for maxSessionDuration for Roles (@eladb in #545).

Changes

  • @aws-cdk/aws-lambda (BREAKING): most classes renamed to be shorter and more in line with official service naming (Lambda renamed to Function or ommitted) (@eladb in #550)
  • @aws-cdk/aws-codepipeline (BREAKING): move all CodePipeline actions from @aws-cdk/aws-xxx-codepipeline packages into the regular @aws-cdk/aws-xxx service packages (@skinny85 in #459).
  • @aws-cdk/aws-custom-resources (BREAKING): package was removed, and the Custom Resource construct added to the @aws-cdk/aws-cloudformation package (@rix0rrr in #513)

Fixes

  • @aws-cdk/aws-lambda: Lambdas that are triggered by CloudWatch Events now show up in the console, and can only be triggered the indicated Event Rule. BREAKING for middleware writers (as this introduces an API change), but transparent to regular consumers (@eladb in #558)
  • @aws-cdk/aws-codecommit: fix a bug where pollForSourceChanges could not be set to false (@maciejwalkowiak in #534)
  • aws-cdk: don't fail if the ~/.aws/credentials file is missing (@RomainMuller in #541)
  • @aws-cdk/aws-cloudformation: fix a bug in the CodePipeline actions to correctly support TemplateConfiguration (@mindstorms6 in #571).
  • @aws-cdk/aws-cloudformation: fix a bug in the CodePipeline actions to correctly support ParameterOverrides (@mindstorms6 in #574).

Known Issues

  • cdk init will try to init a git repository and fail if no global user.name and user.email have been configured.

0.8.1 - 2018-08-08

Features

  • aws-cdk: Support --profile in command-line toolkit (@rix0rrr in #517)
  • @aws-cdk/cdk: Introduce Default construct id (@rix0rrr in #496)
  • @aws-cdk/aws-lambda: Add LambdaRuntime.DotNetCore21 (@Mortifera in #507)
  • @aws-cdk/runtime-values (BREAKING): rename 'rtv' to 'runtime-values' (@rix0rrr in #494)
  • @aws-cdk/aws-ec2: Combine Connections and DefaultConnections classes (@rix0rrr in #453)
  • @aws-cdk/aws-codebuild: allow buildSpec parameter to take a filename (@rix0rrr in #470)
  • @aws-cdk/aws-cloudformation-codepipeline: add support for CloudFormation CodePipeline actions (@mindstorms6 and @rix0rrr in #525).
  • docs: Improvements to Getting Started (@eladb in #462)
  • docs: Updates to README (@Doug-AWS in #456)
  • docs: Upgraded jsii-pacmak to 0.6.4, which includes "language-native" type names and package coordinates (@RomainMuller in awslabs/jsii#130)

Bug fixes

0.8.0 - 2018-07-31

This is the first public release of the AWS CDK!

0.7.4 - 2018-07-26

Highlights

  • A huge shout-out to our first external contributor, @moofish32, for many valuable improvements to the EC2 VPC construct (@moofish32 in #250).
  • The AWS::CDK::Metadata resource is injected to templates to analyze usage and notify about deprecated modules to improve security. To opt-out, use the switch --no-version-reporting or set version-reporting to false in your cdk.json (@RomainMuller in [#221]).
  • Added capability for bundling local assets (files/directories) and referencing them in CDK constructs. This allows, for example, to define Lambda functions with runtime code in the same project and deploy them using the toolkit (@eladb in #371).
  • Reorganization of CodePipeline actions into separate libraries (@skinny85 in #401 and #402).
  • A new library for CloudWatch Logs (@rix0rrr in #307).

AWS Construct Library

  • BREAKING: All AWS libraries renamed from @aws-cdk/xxx to @aws-cdk/aws-xxx in order to avoid conflicts with framework modules (@RomainMuller in #384).
  • BREAKING: The @aws-cdk/resources module has been removed. Low-level CloudFormation resources (e.g. BucketResource) are now integrated into their respective library under the cloudformation namespace to improves discoverability and organization of the layers (@RomainMuller in #264).

Framework

  • Introducing CDK Assets which are local files or directories that can be "bundled" into CDK constructs and apps. During deployment assets are packaged (i.e. zipped), uploaded to S3 and their deployed location can be referenced in CDK apps via the s3BucketName and s3ObjectKey and s3Url and read permissions can be granted via asset.grantRead(principal) (@eladb in #371)
  • Return dummy values instead of fail synthesis if environmental context (AZs, SSM parameters) doesn't exist in order to support unit tests. When synthesizing through the toolkit, an error will be displayed if the context cannot be found (@eladb in #227)
  • Added construct.addError(msg), addWarning(msg) and addInfo(msg) which will emit messages during synthesis via the toolkit. Errors will fail synthesis (unless --ignore-errors is used), warnings will be displayed and will fail synthesis if --strict is used (@eladb in #227)

Command Line Toolkit

  • The toolkit now injects a special CloudFormation resource AWS::CDK::Metadata to all synthesized templates which includes library versions used in the app. This allows the CDK team to analyze usage and notify users if they use deprecated versions (@RomainMuller in [#221]).
  • Bug fix: Fixed "unknown command: docs" (@RomainMuller in #256)
  • Changed output of cdk list to just print stack names (scripting-compatible). Use cdk ls -l to print full info (@eladb in #380)

AWS EC2

  • BREAKING: Add the ability customize subnet configurations. Subnet allocation was changed to improve IP space efficiency. VpcNetwork instances will need to be replaced (@moofish32 in #250)
  • BREAKING: Renamed Fleet to AutoScalingGroup to align with service terminology (@RomainMuller in #318)

AWS Lambda

  • Supports runtime code via local files or directories through assets (@eladb in #405)
  • Support custom execution role in props (@rix0rrr in #205)
  • Add static metricAllConcurrentExecutions and metricAllUnreservedConcurrentExecutions which returns account/region-level metrics for all functions (@rix0rrr in #379)

AWS CloudWatch

  • Added Metric.grantMetricPutData which grants cloudwatch:PutData to IAM principals (@rix0rrr in #214)
  • Bug fix: Allow text included in dashboard widgets to include characters that require JSON-escaping (@eladb in #406).

AWS CloudWatch Logs (new)

  • A new construct library for AWS CloudWatch Logs with support for log groups, metric filters, and subscription filters (@rix0rrr in #307).

AWS S3

  • Added bucketUrl and urlForObject(key) to BucketRef (@eladb in #370)

AWS CodeBuild

  • Add CloudWatch metrics to BuildProject (@eladb in [#407])

AWS CodePipeline

  • BREAKING: Moved CodeCommit and CodeBuild and LambdaInvoke actions from the CodePipeline library to @aws-cdk/aws-xxx-codepipline modules (@skinny85 in #401 and #402).
  • Added attributes pipelineName and pipelineVersion (@eladb in #408)

Docs

  • fix: add instructions and fix Windows setup (@mpiroc in #320)
  • fix: show emphasis of modified code in code snippets (@eladb in #396)

0.7.3 - 2018-07-09

Highlights

  • Introducing Java support (see the Getting Started documentation topic for instructions on how to set up a Java project).
  • Introduce a new programming model for CloudWatch metrics, alarms and dashboards (see the @aws-cdk/cloudwatch documentation).
  • Multiple documentation improvements (open with cdk docs).

Known Issues

  • Missing instructions for Windows Setup (#138)
  • cdk docs works but a message Unknown command: docs is printed (#256)
  • Java: passing null behaves differently than no arguments. Workaround is to build an empty object (#157)

Changes

  • Introduce Java support (@eladb in #229, #245, #148, #149)
  • Changed the way the beta archive is structured to no longer bundle a pre-installed node_modules directory but rather only a local npm repository. This changes the setup instructions to require y-npm i -g aws-cdk to install the toolkit on the system, which is more inline with the setup experience post-beta (@RomainMuller in #161, #162 and awslabs/jsii#43).
  • CloudWatch (new): introduce a rich programming model for metrics, alarms and dashboards (@rix0rrr in #180, #194)
  • S3 (feature): add support for SSE-S3 encryption (@rix0rrr in #257)
  • Lambda (feature): add support for node.js 8.10 runtime (@RomainMuller in #187)
  • Runtime Values (fix): use allowed characters in SSM parameter name when advertising a runtime value (@eladb in #208)
  • SNS (docs): convert examples in README into compiled code (@rix0rrr in #107)
  • Toolkit (feature): introduce cdk doctor to collect information for diagnostics (@RomainMuller in #177)
  • Toolkit (feature): align AWS credentials behavior to AWS CLI (@RomainMuller in #175)
  • Toolkit (performance): cache default AWS account ID on disk (@eladb in #220)
  • Docs: multiple updates (@Doug-AWS in #142)
  • Docs: improve topic on logical IDs (@eladb in #209)
  • Docs: add support for code snippets in multiple tabs (@eladb in #231)
  • Docs: rewrote the "Getting Started" documentation topic to include step-by-step project setup details instead of using cdk-init. This is in order to improve understanding of how the CDK works when users get started (@eladb in #245)
  • Resource bundler: generate .d.ts (@rix0rrr in #172)

0.7.2 - 2018-06-19

Known issues

  • Windows setup has not been vetted and might be broken - no workaround (#138)
  • If region is not defined, error message is unclear - workaround: make sure to define region when running aws configure (#131)
  • cdk docs opens the index instead of the welcome page - workaround: click on "Welcome" in the sidebar (#129)
  • The runtime values library (@aws-cdk/rtv) is broken (#151)

0.7.1 - 2018-06-15

Framework

  • Two-way IAM policy statement additions have been removed for S3 and SNS, because those services treat resource and identity policies as additive. KMS grants are still added on both resource and identity because KMS requires permissions set from both sides.

Toolkit

  • cdk init interface changed to accept the template name as a positional argument, and the language as an option. A --list option was added to allow listing available templates.
  • cdk-beta-npm is a wrapper to npm that executes commands with a local registry that has the CDK packages available. It should be used instead of npm for subcommands such as npm install.
  • CDK now respects AWS_DEFAULT_REGION environment variable if set.

0.7.0 - 2018-06-13

Framework

  • BREAKING: All CDK packages are non under the scope @aws-cdk (e.g. @aws-cdk/s3).
  • BREAKING: The jsii compiler now configures tsconfig.json to produce definition files (files with a .d.ts extension). This requires updating your existing package.json files types key to replace the .ts extension with a .d.ts extension.
  • Java bindings now include static methods and constants.
  • SecretParameter can be used to load values from the SSM parameter store during deployment and use them as Secrets.
  • Stack is locked for mutations during synthesis to protect against accidental changes in lazy values.
  • An overhaul of documentation updates, edits and improvements.

ACM

  • Fix: cloudFrontDefaultCertificate is mutually exclusive with acmCertificateArn.

CloudFront (new)

  • Added a new construct library for AWS CloudFront.

CodeBuild

  • Added support for specifying environment variables at the container and project levels.

CodePipeline

  • Fix: GitHub action "owner" changed to ThirdParty.
  • Removed all fluent APIs
  • Use "master" as the default branch for Source actions
  • BREAKING: AmazonS3SourceProps - renamed key to bucketKey

Custom Resources

  • BREAKING: Require that Lambda is referenced explicitly when defining a custom resource. SingletonLambda can be used to encapsulate the custom resource's lambda function but only have a single instance of it in the stack.

Events (new)

A new cross-stack programming model is introduced to support CloudWatch Events. Event sources implement onXxx methods for various events that can emitted by that source and event targets implement IEventRuleTarget, so they can be polymorphically added to rules.

const repo = new Repository(stack, 'MyRepo', { repositoryName: 'my-repo' });
const project = new BuildProject(stack, 'MyProject', { source: new CodeCommitSource(repo) });

const topic = new Topic(stack, 'MyTopic');
topic.subscribeEmail('Personal', 'myteam@mycompany.com');

project.onStateChange(topic);

Coverage to all event sources and target will be added in subsequent releases.

Supported targets:

  • codebuild.BuildProject
  • codepipline.Pipeline
  • sns.Topic

Supported sources:

  • CodeBuild: onStateChange, onPhaseChange, onBuildStarted, onBuildFailed, onBuildSucceeded.
  • CodeCommit: onEvent, onStateChange, onReferenceCreated, onReferenceUpdated, onReferenceDeleted, onPullRequestStateChange, onCommentOnPullRequest, onCommentOnCommit, onCommit.
  • CodePipeline: pipeline.onStateChange, stage.onStateChange, action.onStateChange.

IAM

  • Add CanonicalUserPrincipal
  • Add statementCount to PolicyDocumennt.
  • Extended support for FederatedPrincipal.

Lambda

  • Add initialPolicy prop which allows specifying a set of PolicyStatements upon definition.

S3

  • Added support for lifecycle rules
  • Add domainName and dualstackDomainName attributes

Serverless

  • version field of FunctionResource is now optional.

SNS

  • BREAKING: subscribeXxx APIs now do not require a name when possible (for queue, Lambda).
  • Unique SID assigned to resource policy statements.

Toolkit

  • cdk docs opens your browser with the bundled documentation content.
  • cdk init interface changed to specify --lang and --type separately.
  • Plug-in architecture improved.

0.6.0 - 2018-05-16

AWS Construct Libraries

The main theme for this release is the stabilization of our framework APIs and an initial set of AWS Construct Libraries.

Previously, CDK users would normally to program against the @aws-cdk/resources library which included generated classes for all CloudFormation resources. For example, the sqs.QueueResource defined the AWS::SQS::Queue CloudFormation resource.

Starting in 0.6, we recommend that users define their infrastructure using a new set of hand-crafted libraries we refer to as AWS Construct Libraries (we used to call these "Layer 2" or "L2"). These libraries include CDK constructs with rich and powerful object-oriented APIs for defining infrastructure.

For example:

const vpc = new VpcNetwork(this, 'MyVpc');

const fleet = new Fleet(this, 'MyFleet', {
    vpc, instanceType: new InstanceTypePair(InstanceClass.M4, InstanceSize.XLarge),
    machineImage: new AmazonLinuxImage()
});

const clb = new ClassicLoadBalancer(this, 'LB', {
    vpc, internetFacing: true
});

clb.addListener({ externalPort: 80 });
clb.addTarget(fleet);

Synthesizing this stack to the us-east-1 region (which has 6 availability zones) will result in a CloudFormation template that contains 72 resources of 17 different resource types.

Construct initializers now include a name

All constructs in a CDK stack must have a name unique amongst its siblings. Names are used to allocate stack-wide logical IDs for each CloudFormation resource. Prior to this release, the name of the class was implicitly used as a default name for the construct. As much as this was convenient, we realized it was misleading and potentially unsafe, since a change in a class name will result in changes to all logical IDs for all resources created within that tree, and changes to logical IDs result in resource replacement since CloudFormation cannot associate the existing resource with the new resource (this is the purpose of logical IDs in CloudFormation).

Therefore, we decided construct names deserve an explicit and prominent place in our programming model and starting from this release, they have been promoted to the 2nd argument of all initializers.

new MyConstruct(parent, name, props);

New scheme for allocating CloudFormation logical IDs

In order to ensure uniqueness of logical IDs within a stack, we need to reflect the resource's full CDK path within it's logical ID. Prior to this release, logical IDs were a simple concatenation of the path components leading up to the resource. However, this could potentially create unresolvable conflicts ("a/b/c" == "ab/c").

Since logical IDs may only use alphanumeric characters and also restricted in length, we are unable to simply use a delimited path as the logical ID. Instead IDs are allocated by concatenating a human-friendly rendition from the path (components, de-duplicate, trim) with a short MD5 hash of the delimited path:

VPCPrivateSubnet2RouteTable0A19E10E
<-----------human---------><-hash->

One exception to this scheme is resources which are direct children of the Stack. Such resources will use their name as a logical ID (without the hash). This is done to support easier migration from existing CloudFormation templates.

Renaming logical IDs to avoid destruction of resources

If you have CDK stacks deployed with persistent resources such as S3 buckets or DynamoDB tables, you may want to explicitly "rename" the new logical IDs to match your existing resources.

First, make sure you compare the newly synthesized template with any deployed stacks. cdk diff will tell you which resources will be destroyed if you deploy this update:

[-] Destroying MyTable (type: AWS::DynamoDB::Table)
[+] Creating MyTableCD117FA1 (type: AWS::DynamoDB::Table)

In order to avoid this, you can use stack.renameLogical(from, to) as follows. Note that renameLogical must be called before the resource is defined as logical IDs are allocated during initialization:

// must be before defining the table (this instanceof Stack)
this.renameLogical('MyTableCD117FA1', 'MyTable');
new dynamodb.Table(this, 'MyTable', { /* .. */ });

Now, cdk diff should indicate no differences.

All "props" types are now interfaces instead of classes

In order to improve the developer experience, we have changed the way we model construct "Props" and now they are defined as TypeScript interfaces. This has a few implications on how to use them:

In TypeScript, new XxxProps() won't work, you will have to simply assign an object literal:

new Queue(this, 'MyQueue', { visibilityTimeoutSec: 300 });

In Java, you can create a concrete object using a builder:

new Queue(this, "MyQueue", QueueProps.builder()
    .withVisibilityTimeout(300)
    .build());

A design pattern for exporting/importing resources

All AWS constructs implement a common pattern which allows treating resources defined within the current stack and existing resources to be treated via a common interface:

For example, when defining a Pipeline, you can supply an artifacts bucket.

The bucket is defined within the same stack:

const bucket = new Bucket(this, 'MyArtifactsBucket');
new Pipeline(this, 'MyCoolPipeline', { artifactsBucket: bucket });

You can also import a bucket by just specifying its name:

const bucket = Bucket.import({ bucketName: new BucketName('my-bucket') });
new Pipeline(this, 'MyCoolPipeline', { artifactsBucket: bucket });

Or you can export the bucket from another stack and import it:

// some other stack:
const bucket = new Bucket(otherStack, 'MyBucket');
const externalBucket = bucket.export();
// bucketRef contains tokens that allow you to pass it into `import`.

// my stack:
const importedBucket = Bucket.import(this, 'OtherArtifactsBucket', externalBucket);
new Pipeline(this, 'MyCoolPipeline', { artifactsBucket: importedBucket });

Region-aware APIs for working with machine images (AMIs)

The @aws-cdk/ec2 library exposes a new API for region-aware AMI discovery:

const ami = new AmazonLinuxImage({
    edition: AmazonLinuxEdition.Standard, // default
    virtualization: AmazonLinuxVirt.HVM,  // default
    storage: AmazonLinuxStorage.EBS       // default is GeneralPurpose
});

new Fleet(this, 'MyAmazonLinuxFleet', { machineImage: ami, ... });

For Windows:

const ami = new WindowsImage(WindowsVersion.WindowsServer2016EnglishNanoBase);
new Fleet(this, 'MyWindowsFleet', { machineImage: ami, ... });

Or, a mapping utility:

const ami = new GenericLinuxImage({
    'us-east-1': 'ami-62bda218',
    'eu-west-1': 'ami-773acbcc'
});

new Fleet(this, 'MySuseFleet', { machineImage: ami, ... });

A rich programming model for Code Suite services

The @aws-cdk/codebuild, @aws-cdk/codecommit and @aws-cdk/codepipeline construct libraries include rich APIs for defining continuous integration pipelines and builds.

The following code defines a pipeline with a CodeCommit source and CodeBuild build step. The pipeline is created with an artifacts bucket and a role, and least-privilege policy documents are automatically generated.

// define a CodeCommit repository
const repo = new Repository(stack, 'MyRepo', { repositoryName: 'my-repo' });

// define a pipeline with two stages ("source" and "build")
const pipeline  = new Pipeline(stack, 'Pipeline');
const sourceStage = new Stage(pipeline, 'source');
const buildStage  = new Stage(pipeline, 'build');

// associate the source stage with the code commit repository
const source = new codecommit.PipelineSource(sourceStage, 'source', {
    artifactName: 'SourceArtifact',
    repository: repo,
});

// associate the build stage with code build project
new codebuild.PipelineBuildAction(buildStage, 'build', {
    project: new BuildProject(stack, 'MyBuildProject', { source: new CodePipelineSource() },
    source
});

Inline JavaScript Lambda Functions

The @aws-cdk/lambda library includes an InlineJavaScriptLambda construct which makes it very easy to implement simple node.js Lambda functions with code inline in the CDK.

This CDK program defines an S3 Bucket and a Lambda function, and sets all the needed permissions. When the function is invoked, a file named 'myfile.txt' will be uploaded to the bucket with the text "Hello, world". The physical bucket name is passed through via the BUCKET_NAME environment variable.

const bucket = new Bucket(this, 'MyBucket');

const lambda = new InlineJavaScriptLambda(this, 'MyLambda', {
    environment: {
        BUCKET_NAME: bucket.bucketName
    },
    handler: {
        fn: (event: any, context: any, callback: any) => {
            const s3 = new require('aws-sdk').S3();

            const req = {
                Bucket: process.env.BUCKET_NAME,
                Key: 'myfile.txt',
                Body: 'Hello, world'
            };

            return s3.upload(req, (err, data) => {
                if (err) return callback(err);
                console.log(data);
                return callback();
            });
        }
    }
});

// grant the Lambda execution role read/write permissions for the bucket
// this also adds a corresponding bucket resource policy
bucket.grantReadWrite(lambda.role);

Resource and role IAM policies and grants

All AWS constructs now expose APIs for naturally adding statements to their resource or role policies. Constructs may have addToRolePolicy(statement) or addToResourcePolicy(statement) methods, which can be used to mutate the policies associated with a resource.

The statement is a PolicyStatement object with a rich API for producing IAM statements. This is an excerpt from the implementation of topic.subscribeQueue:

queue.addToResourcePolicy(new PolicyStatement()
    .addResource(queue.queueArn)
    .addAction('sqs:SendMessage')
    .addServicePrincipal('sns.amazonaws.com')
    .setCondition('ArnEquals', { 'aws:SourceArn': this.topicArn }));

The S3 bucket construct has a set of "grant" methods (grantRead, grantReadWrite) which accept a principal resource (user, role or group) and an optional key prefix pattern and will render reciprocal IAM permissions, both in the principal's policy and the bucket policy:

const reader = new User(this, 'Reader');
const bucket = new Bucket(this, 'MyBucket');
bucket.grantRead(reader);

Synthesizes to:

Resources:
  ReaderF7BF189D:
    Type: AWS::IAM::User
  ReaderDefaultPolicy151F3818:
    Type: AWS::IAM::Policy
    Properties:
      PolicyDocument:
        Statement:
        - Action: [ "s3:GetObject*", "s3:GetBucket*", "s3:List*" ]
          Effect: Allow
          Resource:
          - { "Fn::GetAtt": [ "MyBucketF68F3FF0", "Arn" ] }
          - { "Fn::Join": [ "", [ { "Fn::GetAtt": [ "MyBucketF68F3FF0", "Arn" ] }, "/", "*" ] ] }
        Version: '2012-10-17'
      PolicyName: ReaderDefaultPolicy151F3818
      Users: [ { "Ref": "ReaderF7BF189D" } ]
  MyBucketF68F3FF0:
    Type: AWS::S3::Bucket
  MyBucketPolicyE7FBAC7B:
    Type: AWS::S3::BucketPolicy
    Properties:
      Bucket: { "Ref": "MyBucketF68F3FF0" }
      PolicyDocument:
        Statement:
        - Action: [ "s3:GetObject*", "s3:GetBucket*", "s3:List*" ]
          Effect: Allow
          Principal:
            AWS: { "Fn::GetAtt": [ "ReaderF7BF189D", "Arn" ] }
          Resource:
          - { "Fn::GetAtt": [ "MyBucketF68F3FF0", "Arn" ] }]
          - { "Fn::Join": [ "", [ { "Fn::GetAtt": [ "MyBucketF68F3FF0", "Arn" ] }, "/", "*" ] ] }
        Version: '2012-10-17'

Security group connections framework

The @aws-cdk/ec2 library includes a rich framework for modeling security group connections between resources such as a fleet, load balancers and databases.

For example, these automatically create appropriate ingress and egress rules in both security groups:

// allow fleet1 top connect to fleet2 on port 80
fleet1.connections.allowTo(fleet2, new TcpPort(80), 'Allow between fleets');

// allow fleet3 to accept connections from a load balancer on ports 60000-65535
fleet3.connections.allowFrom(loadBalancer, new TcpPortRange(60000, 65535), 'Allow from load balancer');

Improvements to attribute classes and tokens

  • Remove the "Attribute" postfix from all generated attribute types. So now, it is QueueArn instead of QueueArnAttribute. "Attribute" postfix from attribute types
  • Simplify the initialization of Token objects (all attribute types are Tokens). They can now be either initialized with a simple value or a lazy function. This means, that now you can write new QueueArn('foo'). This is useful when importing external resources into the stack.

Improvements to the CDK Toolkit

The toolkit now outputs YAML instead of JSON by default.

Added active progress reporting for stack updates.

The diff output has been dramatically improved and provides a structure-aware diff. For example:

[~] Updating TableCD117FA1 (type: AWS::DynamoDB::Table)
        .ProvisionedThroughput:
            .WriteCapacityUnits: 10
    Creating MyQueueE6CA6235 (type: AWS::SQS::Queue)

Library for unit and integration testing

The CDK is now shipped with a library called @aws-cdk/assert which aims to make it easy to write unit and integration tests for CDK libraries and apps. The library leverages the same powerful template diff mechanism used in the toolkit to print rich descriptions.

import { expect } from '@aws-cdk/assert';

const stack = new Stack();
new Queue(stack, 'MyQueue', { visibilityTimeout: 300 });

expect(stack).to(haveResource('AWS::SQS::Queue', { VisibilityTimeout: 300 }));
expect(stack).to(countResources('AWS::SQS::Queue', 1));
expect(stack).toMatch({
    Resources: {
        MyQueue: {
            Type: 'AWS::SQS::Queue',
            Properties: {
                VisibilityTimeout: 300
            }
        }
    }
});

An initial integration testing utility is now available to allow users to implement manually executed CDK integration tests and ensure they are kept up-to-date if the code changes. This is an initial approach until we have a great way to automatically execute them during CI/CD.

Updates to the IAM policy library

The APIs in the IAM policy library have been improved and now provide a richer and more strongly-typed experience.

A class hierarchy around PolicyPrincipal was created to reflect the various principals available: AccountPrincipal, ServicePrincipal, ArnPrincipal, AccountRootPrincipal.

The Arn type now has the ability to format and parse to/from its components:

Arn.fromComponents({
    service: 'dynamodb',
    resource: 'table',
    account: '123456789012',
    region: 'us-east-1',
    partition: 'aws-cn',
    resourceName: 'mytable/stream/label'
});

// and
const bucketArn = Arn.parse('arn:aws:s3:::my_corporate_bucket')
// bucketArn === { partition: 'aws', service: 's3', resource: 'my_corporate_bucket' }

The Permission class was renamed to PolicyStatement and enriched with more strongly typed APIs.

A new library for defining custom CloudFormation resources

A library to facilitate the definition of custom CloudFormation resources and exposing them as regular CDK constructs is now shipped with the CDK.

0.5.0 - 2018-03-29

AWS Resource Constructs (L1)

  • All CloudFormation resource constructs are now available from the @aws-cdk/resources package under their dedicated AWS service's namespace. we have been calling these resource constructs Layer 1 (or "L1 constructs").
  • All resource constructs now have the Resource suffix (TableResource instead of Table). This helps differentiate them from the rich AWS constructs we are also introducing in this release.
  • The CloudFormation resource property "Name" is now called "xxxName" (where "xxx" is the name of the resource, like "queue") instead of "resourceName".
  • Updated resources based on the latest CloudFormation resource specification.

Before:

import { Pipeline } from '@aws-cdk/codepipeline';

new Pipeline(this, {
    resourceName: 'MyPipelineName'
});

After:

import { codepipeline } from '@aws-cdk/resources';

new codepipeline.PipelineResource(this, {
    pipelineName: 'MyPipelineName'
});

Framework

  • Introducing CDK Applets which allow instantiating specific CDK stacks using a declarative YAML syntax.
  • As a first step to enable diagnostics features in the toolkit, record logical ID (and stack trace) in metadata for stack elements.
  • Introduce a new scheme for generating CloudFormation logical IDs which adds a hash of the construct path to the generated ID to avoid ID collisions. To opt-in for the new scheme, set hashedLogicalIDs to true when creating a Stack.
  • Allow specifying explicit logicalID for stack elements like Resource Parameter and Output.
  • async exec() changed to run() and validate was changed to be a synchronous method instead of async.
  • Merged @aws-cdk/core into aws-cdk, which now where the core classes of the CDK framework live.
  • The Runtime Values library, which was under @aws-cdk/rtv is now @aws-cdk/rtv.
  • Bugfix: Tags could not be used because they failed validation.
  • Bugfix: Allow "-" in stack names.

Toolkit

  • The toolkit is now called CDK Toolkit instead of "cx Toolkit". This means that the cx command-command line program is now called cdk.
  • Added support large CloudFormation templates using a "toolkit stack" which contains an S3 bucket. This approach may be extended to provide other environment-related facilities in the future and requires that users "bootstrap" the toolkit stack into their environments. The current behavior will not require this stack unless you are trying to deploy a large template.
  • It is now possible to synthesize all stacks into a directory.
  • Allow using globs in cdk deploy to select multiple stacks.
  • Default account ID lookup result is now cached.
  • Better error messages.
  • Improve deploy output.
  • Bugfix: Better error message when the app has no stacks.
  • Bugfix: Distinguish actual "stack missing" from "no credentials".
  • Bugfix: Delete stack in unrecoverable state.
  • Bugfix: Fix an issue where 'deploy' fails because subsequent invocations use the same argument array.
  • Bugfix: prevent crash if ~/.aws/config doesn't exist.

Documentation and Examples

  • Implemented a few advanced examples These examples show how to use IAM policies, environmental context, template inclusion, nested stacks, resource references and using various CloudFormation semantics in the CDK

0.4.0 - 2018-03-05

New Features

  • Environments - this version extends the fidelity of a CDK deployment target from only region to region + account, also referred to as an environment. This allows modeling complete apps that span multiple accounts/regions. To preserve the current behavior, if region/account is not specified, the CDK will default to the AWS SDK region/credential provider chain (~/.aws/config). We will add support for AWS SDK Profiles in a future release. See the Environments section of the CDK README for details).
  • Environmental Context (such as availability zones and SSM parameters) - there are use-cases where CDK stacks need to consult with account and region-specific information when they are synthesized (we call this information "environmental context"). For example, the set of supported availability zones is specific to account and region; the specific ID of certain public AMIs (Amazon Machine Image IDs) as published to the SSM parameter store is specific to each region. See the Environmental Context section in the CDK README for details .
  • Runtime Values - a new mechanism for advertising values such as resource attributes and constants from construction-time to runtime code via the SSM parameter store. See the Runtime Values section in the CDK README for details.
  • Construct Validation - it is now possible to implement a method validate(): string[] for any construct at any layer. Validation methods are all executed before a stack is synthesized and provide an opportunity for constructs to implement validation logic. See the Construct Validation section in the CDK README for details.
  • User-specific cx.json - the toolkit will now incorporate settings from ~/.cx.json. This allows users to supply user-specific settings. Note this file is applied before the project-specific cx.json file is applied.
  • IAM Library Improvements - allow creating IAM documents with a base document, a new class AssumeRolePolicyDocument, allow specifying multiple actions when creating a Permission ob object.
  • stack.findResource(logicalId) - allows retriving a resource object from a stack based on it's calculated logical ID.
  • Windows AMIs are read from SSM parameter store.

Bug Fixes

  • cx Toolkit returns a non-zero exit code when an error occurs.
  • Retain original names of CloudFormation properties instead of auto-capitalizing based on heuristics, which caused some unexpected behavior in certain scenarios.
  • CAPABILITY_NAMED_IAM was added to "cx deploy" by default.

0.3.0 - 2018-01-30

Highlights

  • Java support:
class HelloJavaStack extends Stack {
    public HelloJavaStack(final Construct parent, final StackProps props) {
        super(parent, props);

        VpcNetwork vpc = new VpcNetwork(this);

        new Fleet(this, new FleetProps()
                .withVpcSubnetwork(vpc.getPrivateSubnetwork())
                .withInstanceType(new InstanceType("t2.micro"))
                .withMachineImage(new WindowsMachineImage(0)));
    }
}

  • cx Toolkit now supports standard AWS credentials.

  • CloudFormation pseudo parameters and intrinsic functions are now implemented as normal classes (AwsRegion, AwsStackId, FnConcat) instead of static methods. We might introduce functional sugar at a later stage, but at the lower-level, we want to represent both intrinsic functions and pseudo parameters as classes so we can model their relationship more accurately. For example, all pseudo parameters extend PseudoParameter, all functions extends the Fn, all condition functions extend FnCondition, etc.

Before:

Fn.if_(Fn.equals(param.ref, 'True'), 'Encrypted', Pseudo.NO_VALUE)

After:

new FnIf(new FnEquals(param.ref, 'True'), 'Encrypted', new AwsNoValue())
  • CloudFormation template options (templateFormatVersion, description and transform) are now grouped under Stack.templateOptions instead of directly under Stack.

Before:

stack.description = 'This is my awesome template'

After:

stack.templateOptions.description = 'This is my awesome template'

Known Issues

  • Stack names are limited to alphanumeric characters, so it won't be possible to set stack names to match existing deployed stacks. As a workaround you can use cx --rename to specify the actual stack name to use for diff or deploy. Thanks rmuller@ for reporting.
  • When synthesizing templates, we transform all JSON keys to pascal case to conform with CloudFormation standards, but this also affects JSON blobs that are not CloudFormation such as IAM documents or environment variables.

Non-breaking Changes

  • Added support for CloudFormation Rules.
  • Cloud Executable Interface (CXI): changed semantics from "construct" to "synthesize" (backwards compatible).
  • Tokens: improve error reporting when unable to resolve tokens.

0.2.0 - 2017-12-07

Highlights

Construct Names

  • The initializer signature for constructs has changed and is now: new Construct(parent[, props]), where props is may include an optional name property ("id" is now called "name").
  • If name is not specified, the type name is used as the name. This will only be allowed when there is a single construct of a certain type under a parent.
  • If a parent has more than a single child of the same type, all children must have an explicit names to avoid ambiguity when generating CloudFormation logical IDs.
  • JSX support updated to use name instead of id when producing construct trees.

Before:

new BeautifulConstruct(this, 'MyBeautifulConstruct', { ...props })

After:

new BeautifulConstruct(this) // use defaults
new BeautifulConstruct(this, { ...props })
// or
new BeautifulConstruct(this, { name: 'MyBeautifulConstruct', ...props })

Resource Attribute Types

  • CloudFormation resource attribute properties now return a specialized type per attribute. For example, the sqs.queueArn property returns a QueueArnAttribute object instead of a Token.
  • The Attribute and ArnAttribute classes extend Token and used as base classes for attribute types.
  • Resource names are now added as a prefix to attribute properties (queueArn instead of arn). This is required for future support for duck-typing and polymorphic use of resources of multiple types via a single container.

Before:

const t = new aws.dynamodb.Table(this);
assert(t.arn instanceof Token);

After:

const t = new aws.dynamodb.Table(this);
assert(t.tableArn instanceOf TableArnAttribute);
assert(t.tableArn instanceOf ArnAttribute);
assert(t.tableArn instanceOf Token);

Construct Metadata

  • Constructs can now have metadata entries attached to them via addMetadata(type,data).
  • Each entry will also include the stack trace from which the entry was added, which will later be used to improve the diagnosability of deployment errors.
  • Stack metadata can be obtained using cx-Toolkit via cx metadata.
  • construct.addWarning(msg) attaches a "warning" metadata entry to a construct, which is displayed as a warning when synthesizing or deploying the stack.
  • cx-Toolkit will show warnings upon synthesis also supports --strict mode which will refuse to deploy stacks with warnings.

Example:

const c = new Construct(this);
c.addWarning('this is a warning');
c.addMetadata('type', 'data');
$ cx metadata
{
  "/Stack/Construct": [
    {
      "type": "type",
      "data": "data",
      "trace": [ ... ]
    },
    {
      "type": "warning",
      "data": "this is a warning",
      "trace": [ ... ]
    }
  ]
}
$ cx synth
Warning: this is a warning (at /Stack/Construct)
...

Resource Enrichments

  • Replaced topic.subscribeToXxx with topic.subscribe(target) where target is anything that adheres to the SubscriptionTarget interface (technically it's an abstract class because jsii doesn't support interfaces yet).
  • Removed function.addExecutionRole() - an execution role is automatically created when invoking function.addPermission(p).

Tokens

  • The evaluate method is now called resolve.

CX Toolkit Usability Improvements

  • If an app contains a single stack, no need to specify the stack name.
  • synth --interactive (or synth --interactive --verbose) now displays real-time updates of a template's contents. Really nice for fast iteration;
  • The toolkit now reads cx.json for default arguments. Very useful, for example, to remove the need to specify --app in every invocation.