CDK User Guide should document importing templates

[fulghum]

Many customers will have existing CFN templates they want to use or reference from inside CDK code. We should document this scenario and explain how it works.

[Doug-AWS]

I'll add it to the post-internal-beta to-do list.

[eladb]

There are a few possible options for users who with to use existing templates in CDK apps:

1. The Include construct

You can use the Include construct to load the template into their stack as-is. This basically merges the contents of the template into their CDK stack. The benefit of this is that resources defined in the template can be referenced from CDK constructs that are defined outside the Include.

At the moment, there isn't a "nice" way to find resources in the included template (for example, I'd expect stack.findResource(id) to work, but it's not because the template is included only during synthesis. Therefore, in order to reference resource attributes in an included template, users will need to create an FnGetAtt:

new Include(this, 'ExistingInfra', { 
    template: JSON.parse(fs.readFileSync('./my-template.json')) 
});

// to reference the ARN of a bucket with logical ID MyBucket defined in "my-template.json"
// create an FnGetAtt token:
const bucketArn = new FnGetAtt('MyBucket', 'Arn');

I think we can provide some nice sugar that will allow users to reference resources within the included stack. For example:

const existingInfra = new Include(this, 'ExistingInfra', { 
    template: JSON.parse(fs.readFileSync('./my-template.json')) 
});

const myBucketArn = existingInfra.getAtt('MyBucket', 'Arn');
const myBucketName = existingInfra.ref('MyBucket');

2. Use an existing template as nested stack

See examples in @aws-cdk/quickstarts for how to define a nested stack in your CDK app and reference an existing template. The limitation here is that you will only be able to interact with the template via it's defined parameters and outputs.

3. (not supported yet) Disassembler

We had an idea to take a CloudFormation template and "disassemble" it into CDK code. The resulting code will effectively be a flat list of L1 resources (from @aws-cdk/resources).

The more I am thinking about it the more I think this is not a great approach, for the following reasons:

1. We won't be able to disassemble a template into L2 constructs. This means that it leaves people at the lower-layer of abstraction.
2. The fact that the resulting output doesn't have any structure (since we cannot infer any structure from the template) might encourage people to start grouping these resources into user-defined constructs. That's all good and well, but it will practically mean that the logical IDs will change (when constructs move in the tree, their addresses change and the allocated logical ID will also change). You could manually call stack.renameLogical(from, to) to undo these moves, but it's going to be a very unpleasant experience.

Let's examine if options #1 and #2 provide a good enough story for people with existing templates and see if we want to pursue #3 only if there's a clear use case and demand from users.

[Doug-AWS]

#171

[Doug-AWS]

Part of #1525