Heat/NestedStacks

= Nested Stacks =

Nested Stacks Overview
Nested stacks are a mechanism of using built-in stack definitions for specific resource types. An example is the RDS resource type, which is really a nested MySQL stack.

Amazon refers to this feature as '[Template composition](http://aws.amazon.com/about-aws/whats-new/2011/08/08/announcing-aws-cloudformation-embedded-stacks-and-auto-scaling-enhancements/)' and to the referenced stacks as 'Embedded stacks'. There are some [example template snippets](http://docs.amazonwebservices.com/AWSCloudFormation/latest/UserGuide/quickref-stack.html) and full documentation on the [AWS::CloudFormation::Stack](http://docs.amazonwebservices.com/AWSCloudFormation/latest/UserGuide/aws-properties-stack.html) Resource type.

Nested Stack Design
OLD INFORMATION NOT UPDATED RECENTLY THE DESIGN HAS BEEN REFRESHED PLEASE CONSULT #heat irc channel for latest on this.

Currently, templates are fetched by the Heat API from a file or URL and the entire template text sent to the Heat Engine. However embedded stacks are referenced by URL, and the templates are not normally parsed until they reach the engine. Some options for dealing with this (in ascending order of preference):


 * Check the template for embedded stacks in the API, and include the template text in the request.
 * Fetch only the embedded templates from the engine.
 * Move the fetching of URLs into the engine. We would probably still need a way to pass the full template to handle file (rather than URL) references, since the heat CLI does not necessarily run on the same machine as the engine.

It would be nice if the chosen solution supported relative URLs, ideally including relative paths for files. However the second (and simplest) option would not allow for that, unless we passed both the template _and_ the URL.

Creating a resource type that encapsulates a stack should be relatively straightforward. Parameters for the stack are passed in the encapsulating template. The only outputs required are the stack ID and a stack name, which is derived from the encapsulating template.

We will need to mark encapsulated stacks in the database in some way so that they don't show up in e.g. heat list, since embedded stacks should be managed only in the context of them being resources of the main stack. We should also handle the cases where there are one or more encapsulated stacks that share a name with another stack (whether encapsulated or not).

There may be consequences for Resource startup ordering. Do we need to include the embedded stack's Resources separately in the dependency calculation, or can we treat the whole stack as a black box for those purposes? The former is still quite possible, but requires a little work.