Nested stack support

[eladb]

It should be easy to define nested stacks in the CDK.

This requires a good story behind uploading synthesized templates to S3 and "plugging in" the URL of the nested stack into the parent stack (see #233).

We should have a story on how to reference resources from the parent child in the child stack (i.e. using nested stack "Parameters") and how to reference resources from the child stack in the parent stack (i.e. using "Outputs").

[tvb]

@eladb status? I need nested stack support before I can start using this cdk really.

[eladb]

This should not be too hard to support through assets.

[eladb]

A bit more context/direction/pointers/ideas:

As a user, I'd like to be able to be able to define a nested stack like any other stack in the CDK:

class SmallStack extends Stack {
  // ...
}

class BigStack extends Stack {
  constructor(p: Construct, id: string) {
    new SmallStack(this, 'NestedStack');
  }
}

const app = new App();
new BigStack(app, 'my-awesome-stack');
app.run();

An instance of SmallStack has been added as a child for BigStack. My expected behavior for this would be that SmallStack will be modeled as a nested in the my-awesome-app template.

This technically means that:

1. The CDK app should synthesize two CloudFormation templates: one for my-awesome-app (like today) and the other for the nested stack.
2. The template my-awesome-app will include an AWS::CloudFormation::Stack resource with TemplateURL assigned from a CloudFormation Parameter.
3. Before deploying my-awesome-app, the toolkit should upload the nested stack template to S3 and then assign the location of the uploaded template to the parameter wired to the TemplateURL.

Assets: the protocol between the CDK and the toolkit (defined under the cx-api module) allows CDK apps to emit metadata entries that instruct the toolkit to package and deploy various types of assets (s3 files, s3 directories, docker images) and then reference them through CloudFormation parameters when the stack is deployed, which is effectively what we need here.

[sam-goodwin]

This has implications on how Stacks are instantiated, render toCloudformation and import Output values.

Minor:

• The parent of a stack can now be any Construct, not just an App.
• StackProps.env is irrelevant - nested stacks are always deployed in the same account/region pair.

How to distinguish the behavior of aStack instance when used as a root vs nested stack?

If it's a nested stack, we want to render both its template and the AWS::CloudFormation::Stack resource, passing in parameter values from the parent. Can/should a stack be designed for both use-cases?

interface ChildStackProps extends cdk.StackProps {
  bucketArn?: string; // what does it mean to specify this as a root stack?
}

class ChildStack extends Stack {
  constructor(parent: cdk.Construct, name: string, props: ChildStackProps = {}) {
    super(parent, name, props);

    this.bucketParameter = new cdk.Parameter(this, 'BucketArn', {
      type: 'AWS::S3::Bucket'
    });
    if (props.bucketArn) {
      // how to 'accept' the bucketArn when used as a nested stack?
    }
  }

  // how does toCloudformation distinguish its behavior?
}

Parent stacks import a nested stack's Output value with Fn::GetAtt Outputs.NestedStackOutputName, not Fn::ImportValue.

Do we expect developers to use a different import API when using nested stacks, or re-purpose the existing import and XXXRef convention? Passing around BucketRef works well when the stacks are all root stacks, but the behavior is different for nested stacks, so developers must be aware of where the value came from.

class ParentStack extends Stack {
  constructor(parent: cdk.Construct, name: string) {
    super(parent, name);
    this.child = new ChildStack(this, 'Child');
    // Can I do this? It will use Fn::ImportValue instead of Fn::GetAtt
    const bucket = s3.BucketRef.import(this, 'Bucket', this.child.bucketProps);
  }
}

class ChildStack extends Stack {
  public readonly bucketProps: s3.BucketRefProps;
  constructor(parent: cdk.Construct, name: string) {
    super(parent, name);
    this.bucketProps = new s3.Bucket(this, 'Bucket').export();
  }
}

How does import work for two child stacks in a single hierarchy?

I don't know if two child stacks can import values from each-other, or if they must be proxied through Fn::GetAtt and Parameters via a common parent stack:

class ChildStack extends Stack {
  public readonly bucketProps: s3.BucketRefProps;
  constructor(parent: cdk.Construct, name: string) {
    super(parent, name);
    this.bucketProps = new s3.Bucket(this, 'Bucket').export();
  }
}

class ChildStack2 extends Stack {
  constructor(parent: cdk.Construct, name: string, child: ChildStack) {
    super(parent, name);
    // will this work?
    s3.BucketRef.import(this, 'Bucket', child.bucketProps);
  }
}

[eladb]

Good points. All the cross reference aspects should probably be designed in conjunction with @rix0rrr's work on #1324. Rico proposes to eliminate the need for explicit import/export, which might serve to identify which type of reference this is: between two root stacks, between two nested stacks or between a nested stack and it's parent.

The bucketArn input prop example you provided above may be make complete sense as a root stack as well as a nested stack. A stack subclass is a reusable component that can be instantiated many times within the same app or in different apps, and it may accept inputs. Bear in mind that there should probably be a distinction between a concrete value for bucketArn and a value that includes tokens (cdk.unresolved(props.bucketArn) returns true). In the former case, the value would just propagate naturally to the nested/root stack without any need to utilize deploy-time resolution via CloudFormation parameters. In the latter, tokens must first be resolved (at deploy-time) and only then they can be used, so "magic" need to happen.

All the issues you bring up are relevant and important. However, try to design this in layers. How can we provide support for nested stack with minimal magic and maximum control for the user (can we provide only runtime errors if users attempt to cross the boundaries in the wrong way?). Then, we can see how we can sprinkle magic on top...

Meta: would probably be easier to discuss this design via PR under design/*.md (see Design Process).

[tyron]

Keep in mind that users would expect cdk diff to traverse into the nested stacks and provide a complete list of differences of the application. This is even not supported on CloudFormation yet.

[dougmoscrop]

@tyron yeah it sure isn't, and not only that it basically always returns changes even when nothing has changed.

as a workaround I created some utilities here https://github.com/node-cfn

it implements a poor-mans diff, supporting nested stacks - at least as best as I can. it's probably not as precise as a solution would need to be to meet aws standards; it's a library and I use it in a serverless plugin (https://github.com/dougmoscrop/serverless-plugin-bootstrap) which is responsible for representing the diff textually

I would love to switch that plugin to use the cdk under the hood instead if it could support nested stacks. I don't know if any of my work there could be useful.

Approach wise, it topologically sorts the root stack and then runs a diff on each nested stack, and marks changes if it detects a change in things like the template URL (which is always hashed), or any properties in actual templates themselves, and then any thing that depends on a thing that changed gets marked as changed too (so it can possibly err on the side of falsely marking something as changed, but then the visual diff will reveal that nothing really changed). But it avoids false positives when there actually are no changes.

it doesn't currently support imports or nested stacks within nested stacks, though those could be added.