feat: deprecate "cloudformation" namespace in favor of "CfnXxx" (#1311)

Rename generated CloudFormation resource constructs from `cloudformation.XxxResource` to `CfnXxx`. This fixes #878 and eliminates the use of namespaces in the CDK.

This is done in a backwards compatible way, which means that we still generate the old resources under the `cloudformation` namespace so we can remove them in a subsequent release. Those resources also include a deprecation warning which is emitted upon `cdk synth`.

Documentation updated to reflect changes.

Related: aws/jsii#283 and aws/jsii#270

Author: Elad Ben-Israel

docs/src/aws-construct-lib.rst

@@ -122,9 +122,9 @@ the AWS Construct and patch the underlying resources.
 
 AWS constructs, such as :py:class:`Topic <@aws-cdk/aws-sns.Topic>`, encapsulate
 one or more AWS CloudFormation resources behind their APIs. These resources are
-also represented as constructs under the ``cloudformation`` namespace in each
+also represented as ``CfnXxx`` constructs in each
 library. For example, the :py:class:`@aws-cdk/aws-s3.Bucket` construct
-encapsulates the :py:class:`@aws-cdk/aws-s3.cloudformation.BucketResource`. When
+encapsulates the :py:class:`@aws-cdk/aws-s3.CfnBucket`. When
 a stack that includes an AWS construct is synthesized, the CloudFormation
 definition of the underlying resources are included in the resulting template.
 
@@ -167,11 +167,11 @@ given an :py:class:`s3.Bucket <@aws-cdk/s3.Bucket>` construct:
    const bucket = new s3.Bucket(this, 'MyBucket');
 
    // we use our knowledge that the main construct is called "Resource" and
-   // that it's actual type is s3.cloudformation.BucketResource; const
-   const bucketResource = bucket.findChild('Resource') as s3.cloudformation.BucketResource;
+   // that it's actual type is s3.CfnBucket; const
+   const bucketResource = bucket.findChild('Resource') as s3.CfnBucket;
 
 At this point, ``bucketResource`` represents the low-level CloudFormation resource of type
-:py:class:`s3.cloudformation.BucketResource <@aws-cdk/aws-s3.cloudformation.BucketResource>`
+:py:class:`s3.CfnBucket <@aws-cdk/aws-s3.CfnBucket>`
 encapsulated by our bucket.
 
 :py:meth:`construct.findChild(id) <@aws-cdk/cdk.Construct.findChild>` will fail
@@ -186,7 +186,7 @@ type:
 
    const bucketResource =
       bucket.children.find(c => (c as cdk.Resource).resourceType === 'AWS::S3::Bucket')
-      as s3.cloudformation.BucketResource;
+      as s3.CfnBucket;
 
 From that point, users are interacting with CloudFormation resource classes
 (which extend :py:class:`cdk.Resource <@aws-cdk/cdk.Resource>`), so we will look
@@ -203,7 +203,7 @@ For example, this code:
 
 .. code-block:: ts
 
-   const bucketResource = bucket.findChild('Resource') as s3.cloudformation.BucketResource;
+   const bucketResource = bucket.findChild('Resource') as s3.CfnBucket;
 
    bucketResource.options.metadata = { MetadataKey: 'MetadataValue' };
    bucketResource.options.updatePolicy = {
@@ -321,7 +321,7 @@ to delete values:
       encryption: s3.BucketEncryption.KmsManaged
    });
 
-   const bucketResource = bucket.findChild('Resource') as s3.cloudformation.BucketResource;
+   const bucketResource = bucket.findChild('Resource') as s3.CfnBucket;
    bucketResource.addPropertyOverride('BucketEncryption.ServerSideEncryptionConfiguration.0.EncryptEverythingAndAlways', true);
    bucketResource.addPropertyDeletionOverride('BucketEncryption.ServerSideEncryptionConfiguration.0.ServerSideEncryptionByDefault');
 
@@ -349,19 +349,18 @@ Directly Defining CloudFormation Resources
 -------------------------------------------
 
 It is also possible to explicitly define CloudFormation resources in your stack.
-To that end, instantiate one of the constructs under the ``cloudformation``
-namespace of the dedicated library.
+To that end, instantiate one of the ``CfnXxx`` constructs of the dedicated library.
 
 .. code-block:: ts
 
-   new s3.cloudformation.BucketResource(this, 'MyBucket', {
+   new s3.CfnBucket(this, 'MyBucket', {
       analyticsConfigurations: [
          // ...
       ]
    });
 
 In the rare case where you want to define a resource that doesn't have a
-corresponding ``cloudformation`` class (such as a new resource that was not yet
+corresponding ``CfnXxx`` class (such as a new resource that was not yet
 published in the CloudFormation resource specification), you can instantiate the
 :py:class:`cdk.Resource <@aws-cdk/cdk.Resource>` object:
 

docs/src/cloudformation.rst

@@ -21,9 +21,9 @@ 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 **cloudformation** namespace of each library. For
+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.cloudformation.BucketResource` resource (as well as
+:py:class:`@aws-cdk/aws-s3.CfnBucket` resource (as well as
 other resources, depending on what bucket APIs are used).
 
 .. important::
@@ -39,7 +39,7 @@ Resources
 CloudFormation resource classes are automatically generated from the `AWS
 CloudFormation Resource Specification
 <https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-resource-specification.html>`_
-and available under the **cloudformation** namespace of each AWS library. Their
+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
@@ -51,11 +51,11 @@ resource encrypted with an AWS managed key you can directly specify the
 `KmsMasterKeyId <https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-sqs-queues.html#aws-sqs-queue-kmsmasterkeyid>`_
 property.
 
-.. code-block:: js
+.. code-block:: ts
 
-    import { cloudformation } from '@aws-cdk/aws-sqs';
+    import sqs = require('@aws-cdk/aws-sqs');
 
-    new cloudformation.QueueResource(this, 'MyQueueResource', {
+    new sqs.CfnQueue(this, 'MyQueueResource', {
         kmsMasterKeyId: 'alias/aws/sqs'
     });
 
@@ -82,14 +82,14 @@ use one of the properties available on the resource object.
 The following example configures a |LAM| function's dead letter queue to use a
 the ARN of an |SQS| queue resource.
 
-.. code-block:: js
+.. code-block:: ts
 
-   import { cloudformation as sqscfn } from '@aws-cdk/aws-sqs';
-   import { cloudformation as lambdacfn } from '@aws-cdk/aws-lambda';
+   import sqs = require('@aws-cdk/aws-sqs');
+   import lambda = require('@aws-cdk/aws-lambda');
 
-   const dlq = new sqscfn.QueueResource(this, { name: 'DLQ' });
+   const dlq = new sqs.CfnQueue(this, { name: 'DLQ' });
 
-   new lambdacfn.FunctionResource(this, {
+   new lambda.CfnFunction(this, {
       deadLetterConfig: {
          targetArn: dlq.queueArn
       }
@@ -118,13 +118,13 @@ Parameters
 
 .. NEEDS SOME INTRO TEXT
 
-.. code-block:: js
+.. code-block:: ts
 
-    import { cloudformation } from '@aws-cdk/aws-sns';
+    import sns = require('@aws-cdk/aws-sns');
     import cdk = require('@aws-cdk/cdk');
 
     const p = new cdk.Parameter(this, 'MyParam', { type: 'String' });
-    new cloudformation.TopicResource(this, 'MyTopic', { displayName: p.ref });
+    new sns.CfnTopic(this, 'MyTopic', { displayName: p.ref });
 
 .. _outputs:
 
@@ -135,10 +135,10 @@ Outputs
 
 .. code-block:: js
 
-    import { cloudformation } from '@aws-cdk/aws-sqs';
+    import sqs = require('@aws-cdk/aws-sqs');
     import cdk = require('@aws-cdk/cdk');
 
-    const queue = new cloudformation.QueueResource(this, 'MyQueue');
+    const queue = new sqs.CfnQueue(this, 'MyQueue');
     const out = new cdk.Output(this, 'MyQueueArn', { value: queue.queueArn });
 
     const import = out.makeImportValue();
@@ -153,13 +153,13 @@ Conditions
 
 .. code-block:: js
 
-    import { cloudformation } from '@aws-cdk/aws-sqs';
+    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 cloudformation.QueueResource(this, 'MyQueue');
+    const queue = new sqs.CfnQueue(this, 'MyQueue');
     queue.options.condition = cond;
 
 .. _intrinsic_functions:

examples/cdk-examples-typescript/advanced-usage/index.ts

@@ -1,4 +1,4 @@
-import { cloudformation } from '@aws-cdk/aws-cloudformation';
+import { CfnStack } from '@aws-cdk/aws-cloudformation';
 import ec2 = require('@aws-cdk/aws-ec2');
 import iam = require('@aws-cdk/aws-iam');
 import s3 = require('@aws-cdk/aws-s3');
@@ -55,7 +55,7 @@ class EnvContextExample extends cdk.Stack {
       // render construct name based on it's availablity zone
       const constructName = `InstanceFor${az.replace(/-/g, '').toUpperCase()}`;
 
-      new ec2.cloudformation.InstanceResource(this, constructName, {
+      new ec2.CfnInstance(this, constructName, {
         imageId: ami.imageId,
         availabilityZone: az,
       });
@@ -90,7 +90,7 @@ class IncludeExample extends cdk.Stack {
 
     // add constructs (and resources) programmatically
     new EnvContextExample(parent, 'Example');
-    new sqs.cloudformation.QueueResource(this, 'CDKQueue', {});
+    new sqs.CfnQueue(this, 'CDKQueue', {});
   }
 }
 
@@ -104,7 +104,7 @@ class NestedStackExample extends cdk.Stack {
     // add an "AWS::CloudFormation::Stack" resource which uses the MongoDB quickstart
     // https://aws.amazon.com/quickstart/architecture/mongodb/
     // only non-default values are provided here.
-    new cloudformation.StackResource(this, 'NestedStack', {
+    new CfnStack(this, 'NestedStack', {
       templateUrl: 'https://s3.amazonaws.com/quickstart-reference/mongodb/latest/templates/mongodb-master.template',
       parameters: {
         KeyPairName: 'my-key-pair',
@@ -125,10 +125,10 @@ class ResourceReferencesExample extends cdk.Stack {
   constructor(parent: cdk.App, name: string, props?: cdk.StackProps) {
     super(parent, name, props);
 
-    const topic = new sns.cloudformation.TopicResource(this, 'Topic', {});
-    const queue = new sqs.cloudformation.QueueResource(this, 'Queue', {});
+    const topic = new sns.CfnTopic(this, 'Topic', {});
+    const queue = new sqs.CfnQueue(this, 'Queue', {});
 
-    new sns.cloudformation.SubscriptionResource(this, 'Subscription', {
+    new sns.CfnSubscription(this, 'Subscription', {
       topicArn: topic.ref, // resolves to { Ref: <topic-id> }
       protocol: 'sqs',
       endpoint: queue.queueArn // resolves to { "Fn::GetAtt": [ <queue-id>, "Arn" ] }

examples/cdk-examples-typescript/chat-app/cognito-chat-room-pool.ts

@@ -6,7 +6,7 @@ export class CognitoChatRoomPool extends cdk.Construct {
     super(parent, name);
 
     // Create chat room user pool
-    const chatPool = new cognito.cloudformation.UserPoolResource(this, 'UserPool', {
+    const chatPool = new cognito.CfnUserPool(this, 'UserPool', {
       adminCreateUserConfig: {
         allowAdminCreateUserOnly: false
       },
@@ -26,7 +26,7 @@ export class CognitoChatRoomPool extends cdk.Construct {
     });
 
     // Now for the client
-    new cognito.cloudformation.UserPoolClientResource(this, 'UserPoolClient', {
+    new cognito.CfnUserPoolClient(this, 'UserPoolClient', {
       clientName: 'Chat-Room',
       explicitAuthFlows: [ 'ADMIN_NO_SRP_AUTH' ],
       refreshTokenValidity: 30,

examples/cdk-examples-typescript/cloudformation/index.ts

@@ -5,7 +5,7 @@ class CloudFormationExample extends cdk.Stack {
   constructor(parent: cdk.App) {
     super(parent);
 
-    new sqs.cloudformation.QueueResource(this, 'MyQueue', {
+    new sqs.CfnQueue(this, 'MyQueue', {
       visibilityTimeout: 300
     });
   }

examples/cdk-examples-typescript/custom-resource/index.ts

@@ -1,6 +1,6 @@
 import { CustomResource } from '@aws-cdk/aws-cloudformation';
 import lambda = require('@aws-cdk/aws-lambda');
-import { cloudformation as s3 } from '@aws-cdk/aws-s3';
+import { CfnBucket } from '@aws-cdk/aws-s3';
 import cdk = require('@aws-cdk/cdk');
 import fs = require('fs');
 
@@ -86,7 +86,7 @@ class FailAfterCreatingStack extends cdk.Stack {
     });
 
     // Bucket with an invalid name will fail the deployment and cause a rollback
-    const bucket = new s3.BucketResource(this, 'FailingBucket', {
+    const bucket = new CfnBucket(this, 'FailingBucket', {
       bucketName: 'hello!@#$^'
     });
 

examples/cdk-examples-typescript/resource-overrides/index.ts

@@ -15,7 +15,7 @@ class ResourceOverridesExample extends cdk.Stack {
             encryption: s3.BucketEncryption.KmsManaged
         });
 
-        const bucketResource2 = bucket.findChild('Resource') as s3.cloudformation.BucketResource;
+        const bucketResource2 = bucket.findChild('Resource') as s3.CfnBucket;
         bucketResource2.addPropertyOverride('BucketEncryption.ServerSideEncryptionConfiguration.0.EncryptEverythingAndAlways', true);
         bucketResource2.addPropertyDeletionOverride('BucketEncryption.ServerSideEncryptionConfiguration.0.ServerSideEncryptionByDefault');
 
@@ -25,8 +25,8 @@ class ResourceOverridesExample extends cdk.Stack {
         // Accessing the L1 bucket resource from an L2 bucket
         //
 
-        const bucketResource = bucket.findChild('Resource') as s3.cloudformation.BucketResource;
-        const anotherWay = bucket.children.find(c => (c as cdk.Resource).resourceType === 'AWS::S3::Bucket') as s3.cloudformation.BucketResource;
+        const bucketResource = bucket.findChild('Resource') as s3.CfnBucket;
+        const anotherWay = bucket.children.find(c => (c as cdk.Resource).resourceType === 'AWS::S3::Bucket') as s3.CfnBucket;
         assert.equal(bucketResource, anotherWay);
 
         //
@@ -108,7 +108,7 @@ class ResourceOverridesExample extends cdk.Stack {
         // need to consule the codebase or use the `.map.find` method above
         //
 
-        const lc = asg.findChild('LaunchConfig') as autoscaling.cloudformation.LaunchConfigurationResource;
+        const lc = asg.findChild('LaunchConfig') as autoscaling.CfnLaunchConfiguration;
         lc.addPropertyOverride('Foo.Bar', 'Hello');
     }
 }

examples/cdk-examples-typescript/sns-sqs/index.ts

@@ -20,10 +20,10 @@ class CFN extends cdk.Stack {
   constructor(parent: cdk.App, name: string) {
     super(parent, name);
 
-    const topic = new sns.cloudformation.TopicResource(this, 'MyTopic');
-    const queue = new sqs.cloudformation.QueueResource(this, 'MyQueue');
+    const topic = new sns.CfnTopic(this, 'MyTopic');
+    const queue = new sqs.CfnQueue(this, 'MyQueue');
 
-    new sns.cloudformation.SubscriptionResource(this, 'TopicToQueue', {
+    new sns.CfnSubscription(this, 'TopicToQueue', {
       topicArn: topic.ref, // ref == arn for topics
       endpoint: queue.queueName,
       protocol: 'sqs'
@@ -36,7 +36,7 @@ class CFN extends cdk.Stack {
       .addServicePrincipal('sns.amazonaws.com')
       .setCondition('ArnEquals', { 'aws:SourceArn': topic.ref }));
 
-    new sqs.cloudformation.QueuePolicyResource(this, 'MyQueuePolicy', {
+    new sqs.CfnQueuePolicy(this, 'MyQueuePolicy', {
       policyDocument,
       queues: [ queue.ref ]
     });

packages/@aws-cdk/aws-apigateway/lib/deployment.ts

@@ -1,6 +1,6 @@
 import cdk = require('@aws-cdk/cdk');
 import crypto = require('crypto');
-import { cloudformation } from './apigateway.generated';
+import { CfnDeployment, CfnDeploymentProps } from './apigateway.generated';
 import { RestApiRef } from './restapi-ref';
 
 export interface DeploymentProps  {
@@ -103,13 +103,13 @@ export class Deployment extends cdk.Construct implements cdk.IDependable {
   }
 }
 
-class LatestDeploymentResource extends cloudformation.DeploymentResource {
+class LatestDeploymentResource extends CfnDeployment {
   private originalLogicalId?: string;
   private lazyLogicalIdRequired: boolean;
   private lazyLogicalId?: string;
   private hashComponents = new Array<any>();
 
-  constructor(parent: cdk.Construct, id: string, props: cloudformation.DeploymentResourceProps) {
+  constructor(parent: cdk.Construct, id: string, props: CfnDeploymentProps) {
     super(parent, id, props);
 
     // from this point, don't allow accessing logical ID before synthesis

packages/@aws-cdk/aws-apigateway/lib/method.ts

@@ -1,5 +1,5 @@
 import cdk = require('@aws-cdk/cdk');
-import { cloudformation } from './apigateway.generated';
+import { CfnMethod, CfnMethodProps } from './apigateway.generated';
 import { Integration } from './integration';
 import { MockIntegration } from './integrations/mock';
 import { IRestApiResource } from './resource';
@@ -83,7 +83,7 @@ export class Method extends cdk.Construct {
 
     const defaultMethodOptions = props.resource.defaultMethodOptions || {};
 
-    const methodProps: cloudformation.MethodResourceProps = {
+    const methodProps: CfnMethodProps = {
       resourceId: props.resource.resourceId,
       restApiId: this.restApi.restApiId,
       httpMethod: props.httpMethod,
@@ -94,7 +94,7 @@ export class Method extends cdk.Construct {
       integration: this.renderIntegration(props.integration)
     };
 
-    const resource = new cloudformation.MethodResource(this, 'Resource', methodProps);
+    const resource = new CfnMethod(this, 'Resource', methodProps);
 
     this.methodId = resource.ref;
 
@@ -134,7 +134,7 @@ export class Method extends cdk.Construct {
     return this.restApi.executeApiArn(this.httpMethod, this.resource.resourcePath, 'test-invoke-stage');
   }
 
-  private renderIntegration(integration?: Integration): cloudformation.MethodResource.IntegrationProperty {
+  private renderIntegration(integration?: Integration): CfnMethod.IntegrationProperty {
     if (!integration) {
       // use defaultIntegration from API if defined
       if (this.resource.defaultIntegration) {