feat(core): move all types from "aws-cloudformation" to "core" (#7736)

This commit folds the `CustomResource` and `NestedStack` types from `@aws-cdk/aws-cloudformation` into `@aws-cdk/core` in order to allow code in `core` and other lower layers to use capabilities such as nested stacks and custom resources. This comes at a minor sacrifice to API fidelity: the provider's service token is for custom resources is now passed as a simple `string` instead of a strongly typed `ICustomResourceProvider`. But this is negligible for this type of resource given the high involvement users require to use it anyway. Additionally, the `NestedStack` class accepts a `notificationArns` as a `string[]` instead of an `sns.ITopic[]`. In both cases the API in `@aws-cdk/aws-cloudformation` (which is considered a stable module) remains unchanged with a compatibility layer added. We took this opportunity to change the behavior of custom resources so that it won't pascal-case property names by default. This resolves #4896 and resolves #7035 and supersedes #7034. The API in the aws-cloudformation module are still supported for backwards compatibility but marked as deprecated.
aws · May 4, 2020 · 40fa93a · 40fa93a
1 parent 7363912
commit 40fa93a
Show file tree

Hide file tree

Showing 47 changed files with 1,026 additions and 479 deletions.
diff --git a/packages/@aws-cdk/aws-certificatemanager/lib/dns-validated-certificate.ts b/packages/@aws-cdk/aws-certificatemanager/lib/dns-validated-certificate.ts
@@ -1,4 +1,3 @@
-import * as cfn from '@aws-cdk/aws-cloudformation';
 import * as iam from '@aws-cdk/aws-iam';
 import * as lambda from '@aws-cdk/aws-lambda';
 import * as route53 from '@aws-cdk/aws-route53';
@@ -92,8 +91,8 @@ export class DnsValidatedCertificate extends cdk.Resource implements ICertificat
       resources: [`arn:${cdk.Stack.of(requestorFunction).partition}:route53:::hostedzone/${this.hostedZoneId}`],
     }));
 
-    const certificate = new cfn.CustomResource(this, 'CertificateRequestorResource', {
-      provider: cfn.CustomResourceProvider.lambda(requestorFunction),
+    const certificate = new cdk.CustomResource(this, 'CertificateRequestorResource', {
+      serviceToken: requestorFunction.functionArn,
       properties: {
         DomainName: props.domainName,
         SubjectAlternativeNames: cdk.Lazy.listValue({ produce: () => props.subjectAlternativeNames }, { omitEmpty: true }),

diff --git a/packages/@aws-cdk/aws-certificatemanager/package.json b/packages/@aws-cdk/aws-certificatemanager/package.json
@@ -70,7 +70,6 @@
     "pkglint": "0.0.0"
   },
   "dependencies": {
-    "@aws-cdk/aws-cloudformation": "0.0.0",
     "@aws-cdk/aws-iam": "0.0.0",
     "@aws-cdk/aws-lambda": "0.0.0",
     "@aws-cdk/aws-route53": "0.0.0",
@@ -79,7 +78,6 @@
   },
   "homepage": "https://github.com/aws/aws-cdk",
   "peerDependencies": {
-    "@aws-cdk/aws-cloudformation": "0.0.0",
     "@aws-cdk/aws-iam": "0.0.0",
     "@aws-cdk/aws-lambda": "0.0.0",
     "@aws-cdk/aws-route53": "0.0.0",

diff --git a/packages/@aws-cdk/aws-cloudformation/README.md b/packages/@aws-cdk/aws-cloudformation/README.md
@@ -2,93 +2,11 @@
 <!--BEGIN STABILITY BANNER-->
 ---
 
-![cfn-resources: Stable](https://img.shields.io/badge/cfn--resources-stable-success.svg?style=for-the-badge)
+![Deprecated](https://img.shields.io/badge/deprecated-critical.svg?style=for-the-badge)
 
-![cdk-constructs: Stable](https://img.shields.io/badge/cdk--constructs-stable-success.svg?style=for-the-badge)
+> This API may emit warnings. Backward compatibility is not guaranteed.
 
 ---
 <!--END STABILITY BANNER-->
 
 This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) 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. It will perform whatever actions it needs to, and
-then 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
-
-The following shows an example of a declaring Custom Resource that copies
-files into an S3 bucket during deployment (the implementation of the actual
-Lambda handler is elided for brevity).
-
-[example of Custom Resource](test/example.customresource.lit.ts)
-
-The [aws-cdk-examples repository](https://github.com/aws-samples/aws-cdk-examples) has
-examples for adding custom resources.
-
-#### References
-
-See the following section of the docs on details to write Custom Resources:
-
-* [Introduction](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-custom-resources.html)
-* [Reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/crpg-ref.html)
-* [Code Reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-lambda-function-code.html)
-
-### Nested Stacks
-
-[Nested stacks](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-nested-stacks.html) are stacks created as part of other stacks. You create a nested stack within another stack by using the `NestedStack` construct.
-
-As your infrastructure grows, common patterns can emerge in which you declare the same components in multiple templates. You can separate out these common components and create dedicated templates for them. Then use the resource in your template to reference other templates, creating nested stacks.
-
-For example, assume that you have a load balancer configuration that you use for most of your stacks. Instead of copying and pasting the same configurations into your templates, you can create a dedicated template for the load balancer. Then, you just use the resource to reference that template from within other templates.
-
-The following example will define a single top-level stack that contains two nested stacks: each one with a single Amazon S3 bucket:
-
-```ts
-import { Stack, Construct, StackProps } from '@aws-cdk/core';
-import * as cfn from '@aws-cdk/aws-cloudformation';
-import * as s3 from '@aws-cdk/aws-s3';
-
-class MyNestedStack extends cfn.NestedStack {
-  constructor(scope: Construct, id: string, props?: cfn.NestedStackProps) {
-    super(scope, id, props);
-
-    new s3.Bucket(this, 'NestedBucket');  
-  }
-}
-
-class MyParentStack extends Stack {
-  constructor(scope: Construct, id: string, props?: StackProps) {
-    super(scope, id, props);
-
-    new MyNestedStack(this, 'Nested1');
-    new MyNestedStack(this, 'Nested2');
-  }
-}
-```
-
-Resources references across nested/parent boundaries (even with multiple levels of nesting) will be wired by the AWS CDK
-through CloudFormation parameters and outputs. When a resource from a parent stack is referenced by a nested stack,
-a CloudFormation parameter will automatically be added to the nested stack and assigned from the parent; when a resource
-from a nested stack is referenced by a parent stack, a CloudFormation output will be automatically be added to the
-nested stack and referenced using `Fn::GetAtt "Outputs.Xxx"` from the parent.
-
-Nested stacks also support the use of Docker image and file assets.
diff --git a/packages/@aws-cdk/aws-cloudformation/lib/cloud-formation-capabilities.ts b/packages/@aws-cdk/aws-cloudformation/lib/cloud-formation-capabilities.ts
@@ -1,5 +1,6 @@
 /**
  * Capabilities that affect whether CloudFormation is allowed to change IAM resources
+ * @deprecated use `core.CfnCapabilities`
  */
 export enum CloudFormationCapabilities {
   /**

diff --git a/packages/@aws-cdk/aws-cloudformation/lib/custom-resource.ts b/packages/@aws-cdk/aws-cloudformation/lib/custom-resource.ts
@@ -1,7 +1,6 @@
 import * as lambda from '@aws-cdk/aws-lambda';
 import * as sns from '@aws-cdk/aws-sns';
-import { CfnResource, Construct, RemovalPolicy, Resource, Token } from '@aws-cdk/core';
-import { CfnCustomResource } from './cloudformation.generated';
+import * as core from '@aws-cdk/core';
 
 /**
  * Collection of arbitrary properties
@@ -21,14 +20,15 @@ export interface CustomResourceProviderConfig {
 
 /**
  * Represents a provider for an AWS CloudFormation custom resources.
+ * @deprecated use `core.ICustomResourceProvider`
  */
 export interface ICustomResourceProvider {
   /**
    * Called when this provider is used by a `CustomResource`.
    * @param scope The resource that uses this provider.
    * @returns provider configuration
    */
-  bind(scope: Construct): CustomResourceProviderConfig;
+  bind(scope: core.Construct): CustomResourceProviderConfig;
 }
 
 /**
@@ -68,13 +68,14 @@ export class CustomResourceProvider implements ICustomResourceProvider {
    */
   private constructor(public readonly serviceToken: string) { }
 
-  public bind(_: Construct): CustomResourceProviderConfig {
+  public bind(_: core.Construct): CustomResourceProviderConfig {
     return { serviceToken: this.serviceToken };
   }
 }
 
 /**
  * Properties to provide a Lambda-backed custom resource
+ * @deprecated use `core.CustomResourceProps`
  */
 export interface CustomResourceProps {
   /**
@@ -142,103 +143,21 @@ export interface CustomResourceProps {
    *
    * @default cdk.RemovalPolicy.Destroy
    */
-  readonly removalPolicy?: RemovalPolicy;
+  readonly removalPolicy?: core.RemovalPolicy;
 }
 
 /**
- * Custom resource that is implemented using a Lambda
- *
- * As a custom resource author, you should be publishing a subclass of this class
- * that hides the choice of provider, and accepts a strongly-typed properties
- * object with the properties your provider accepts.
+ * Deprecated.
+ * @deprecated use `core.CustomResource`
  */
-export class CustomResource extends Resource {
-  private readonly resource: CfnResource;
-
-  constructor(scope: Construct, id: string, props: CustomResourceProps) {
-    super(scope, id);
-
-    const type = renderResourceType(props.resourceType);
-    const providerConfig = props.provider.bind(this);
-    this.resource = new CfnResource(this, 'Default', {
-      type,
-      properties: {
-        ServiceToken: providerConfig.serviceToken,
-        ...uppercaseProperties(props.properties || {}),
-      },
-    });
-
-    this.resource.applyRemovalPolicy(props.removalPolicy, {
-      default: RemovalPolicy.DESTROY,
+export class CustomResource extends core.CustomResource {
+  constructor(scope: core.Construct, id: string, props: CustomResourceProps) {
+    super(scope, id, {
+      pascalCaseProperties: true,
+      properties: props.properties,
+      removalPolicy: props.removalPolicy,
+      resourceType: props.resourceType,
+      serviceToken: core.Lazy.stringValue({ produce: () => props.provider.bind(this).serviceToken }),
     });
   }
-
-  /**
-   * The physical name of this custom resource.
-   */
-  public get ref() {
-    return this.resource.ref;
-  }
-
-  /**
-   * Returns the value of an attribute of the custom resource of an arbitrary
-   * type. Attributes are returned from the custom resource provider through the
-   * `Data` map where the key is the attribute name.
-   *
-   * @param attributeName the name of the attribute
-   * @returns a token for `Fn::GetAtt`. Use `Token.asXxx` to encode the returned `Reference` as a specific type or
-   * use the convenience `getAttString` for string attributes.
-   */
-  public getAtt(attributeName: string) {
-    return this.resource.getAtt(attributeName);
-  }
-
-  /**
-   * Returns the value of an attribute of the custom resource of type string.
-   * Attributes are returned from the custom resource provider through the
-   * `Data` map where the key is the attribute name.
-   *
-   * @param attributeName the name of the attribute
-   * @returns a token for `Fn::GetAtt` encoded as a string.
-   */
-  public getAttString(attributeName: string): string {
-    return Token.asString(this.getAtt(attributeName));
-  }
-}
-
-/**
- * Uppercase the first letter of every property name
- *
- * It's customary for CloudFormation properties to start with capitals, and our
- * properties to start with lowercase, so this function translates from one
- * to the other
- */
-function uppercaseProperties(props: Properties): Properties {
-  const ret: Properties = {};
-  Object.keys(props).forEach(key => {
-    const upper = key.substr(0, 1).toUpperCase() + key.substr(1);
-    ret[upper] = props[key];
-  });
-  return ret;
-}
-
-function renderResourceType(resourceType?: string) {
-  if (!resourceType) {
-    return CfnCustomResource.CFN_RESOURCE_TYPE_NAME;
-  }
-
-  if (!resourceType.startsWith('Custom::')) {
-    throw new Error(`Custom resource type must begin with "Custom::" (${resourceType})`);
-  }
-
-  const typeName = resourceType.substr(resourceType.indexOf('::') + 2);
-  if (typeName.length > 60) {
-    throw new Error(`Custom resource type length > 60 (${resourceType})`);
-  }
-
-  if (!/^[a-z0-9_@-]+$/i.test(typeName)) {
-    throw new Error(`Custom resource type name can only include alphanumeric characters and _@- (${typeName})`);
-  }
-
-  return resourceType;
 }