Embed stacks within other stacks using nested stacks - AWS CloudFormation
Splitting a CloudFormation templatePerforming stack operations on nested stacksRelated information

Embed stacks within other stacks using nested stacks

Nested stacks are stacks created as part of other stacks. You create a nested stack within another stack by using the AWS::CloudFormation::Stack resource.

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.

Nested stacks can themselves contain other nested stacks, resulting in a hierarchy of stacks, as in the diagram below. The root stack is the top-level stack to which all the nested stacks ultimately belong. In addition, each nested stack has an immediate parent stack. For the first level of nested stacks, the root stack is also the parent stack. in the diagram below, for example:

  • Stack A is the root stack for all the other, nested, stacks in the hierarchy.

  • For stack B, stack A is both the parent stack, and the root stack.

  • For stack D, stack C is the parent stack; while for stack C, stack B is the parent stack.

Nested stacks, which are created as part of another stack, have an immediate parent stack, and the top-level root stack.

Splitting a CloudFormation template

This example demonstrates how to take a single, large CloudFormation template and reorganize it into a more structured and reusable design using nested templates. Initially, the "Before nesting stacks" template shows all the resources defined in one file. This can become messy and hard to manage as the number of resources grows. The "After nesting stacks" template splits up the resources into smaller, separate templates called nested stacks. Each nested stack handles a specific set of related resources, making the overall structure more organized and easier to maintain.

Before nesting stacks

After nesting stacks

 
AWSTemplateFormatVersion: '2010-09-09'
Parameters:
  InstanceType:
    Type: String
    Default: 't2.micro'
    Description: 'The EC2 instance type'
  
  Environment:
    Type: String
    Default: 'Production'
    Description: 'The deployment environment'

Resources:
  MyEC2Instance:
    Type: 'AWS::EC2::Instance'
    Properties:
      ImageId: ami-1234567890abcdef0
      InstanceType: !Ref InstanceType

  MyS3Bucket:
    Type: 'AWS::S3::Bucket'
 
AWSTemplateFormatVersion: '2010-09-09'
Resources:
  MyFirstNestedStack:
    Type: 'AWS::CloudFormation::Stack'
    Properties:
      TemplateURL: 'https://s3.amazonaws.com/amzn-s3-demo-bucket/first-nested-stack.yaml'
      Parameters:
        # Pass parameters to the nested stack if needed
        InstanceType: 't3.micro'

  MySecondNestedStack:
    Type: 'AWS::CloudFormation::Stack'
    Properties:
      TemplateURL: 'https://s3.amazonaws.com/amzn-s3-demo-bucket/second-nested-stack.yaml'
      Parameters:
        # Pass parameters to the nested stack if needed
        Environment: 'Testing'
    DependsOn: MyFirstNestedStack

Performing stack operations on nested stacks

When you have a stack that contains nested stacks, you need to be careful and handle the nested stacks correctly when doing certain actions. Some stack operations, such as stack updates, should be initiated from the root stack rather than performed directly on nested stacks themselves. Additionally, sometimes the presence of the nested stacks can affect how operations on the root stack are performed.

Use the following procedures to find the root stack and nested stacks.

To view the root stack of a nested stack

  1. Sign in to the AWS Management Console and open the AWS CloudFormation console at https://console.aws.amazon.com/cloudformation.

  2. On the Stacks page, choose the name of the nested stack you want to view the root stack of.

    Nested stacks display NESTED above their stack name.

  3. On the Stack info tab, in the Overview section, choose the stack name listed as Root stack.

To view the nested stacks that belong to a root stack

  1. From the root stack whose nested stacks you want to view, choose the Resources tab.

  2. In the Type column, look for resources of type AWS::CloudFormation::Stack.