Deploying Nested Stacks

Overview

Nested applications or stacks are stacks that contain one or more other applications, which are all deployed together. Such a stack has a top-level directory that contains a configuration template (typically a template.yaml file) and may contain shared resources. Additionally, each nested stack also contains its own configuration template. Code may be stored in one top-level repository (i.e. a mono-repo) or in multiple repositories, where each stack corresponds to its own repo.

This is an example of the directory structure for a sample nested application:

.
├── MyNestedApp                        <-- Nested application
│   ├── src                            <-- Nested function source directory
│   │   └── NestedFunction/
│   └── template.yaml                  <-- Nested SAM infrastructure-as-code template
├── MyNestedApp2                       <-- Another nested application
│   ├── src                            <-- Nested function source directory
│   │   └── NestedFunction/
│   └── template.yaml                  <-- Nested SAM infrastructure-as-code template
├── deployHooks/                       <-- Directory for storing deployment hooks
├── src                                <-- Top-level function source directory
│   └── TopLevelFunction/
├── .stackery-config.yaml              <-- Default CLI parameters for root directory
└── template.yaml                      <-- Top-level SAM infrastructure-as-code template

The example above has a top-level application at the root with its own src/ directory where top-level functions can be scaffolded. Then, each application has a directory at the root, and its own IoC template file as well a nestedApp/src/ directory for that application's function files.

The top-level application looks like this in the Stackery Dashboard:

In the example above, each nested application is only shown in its top-level view. However, it's possible to edit each nested app as its own stack in Stackery, as we will demonstrate below.

Structure of a nested stack

Nested applications are declared in the root template.yaml file as a resource of type 'application' or 'stack'. In an AWS SAM template, both AWS::Serverless::Application and AWS::CloudFormation::Stack resource types are allowed. Additionally, stacks from the AWS Serverless Application Repository (SAR) are permitted as well, and can be referenced by their ARNs.

The template below includes a nested local application as well as one from the SAR:

AWSTemplateFormatVersion: 2010-09-09
Transform: AWS::Serverless-2016-10-31
Resources:
  MyNestedApp:
    Type: AWS::Serverless::Application
    Properties:
      Location: MyNestedApp/template.yaml
  AnotherApp:
    Type: AWS::Serverless::Application
    Properties:
      Location:
        ApplicationId: arn:aws:serverlessrepo:us-east-1:173334852312:applications/alexa-skills-kit-nodejs-factskill
        SemanticVersion: 2.0.5

In this example, both MyNestedApp and AnotherApp have their own IoC template files, though only the one for MyNestedApp is included in the repository under ./MyNestedApp/template.yaml, as AnotherApp is deployed from the referenced template.

Setting up a nested application

The easiest way to set up a nested stack is locally with the Stackery CLI.

1. Open a terminal or shell, and enter stackery init -n my-nested-stack
2. Navigate to the newly-created my-nested-stack directory and open my-nested-stack/template.yaml
3. Paste the following on the third line and save the file

Resources:
  MyNestedApp:
    Type: AWS::Serverless::Application
    Properties:
      Location: MyNestedApp/template.yaml
  MyNestedApp2:
    Type: AWS::Serverless::Application
    Properties:
      Location: MyNestedApp2/template.yaml

4. In the terminal, cd to the my-nested-stack directory and enter stackery init -n MyNestedApp
5. Enter stackery init -n MyNestedApp2
6. Enter cd MyNestedApp and run stackery edit. You can now visually architect your first application
7. Repeat the previous step for MyNestedApp2
8. Optionally, you can run stackery edit in the root my-nested-stack directory if you would like to add any top-level resources

In the example nested-application stack we referenced above, the nested applications look like this:

It's important to note that while it's not possible to have two functions with the same name in the same stack, it's perfectly acceptable to have function names repeat between nested stacks, such as the NestedFunction above.

Working with nested applications

As of CLI version 3.9.0, nested stacks can be deployed with the Stackery CLI just like any other stack.

Deploying nested apps

To deploy a nested application using the local deployment strategy, be sure you're deploying from the root directory of the entire application. A deployment using CodeBuild will look the same as a deployment for a non-nested stack. The deployment output will include information about top-level functions as well as functions deployed with the nested stacks.

After deployment, you also can run stackery describe --verbose for your top-level stack to get a list of all the resources across your deployed applications:

Locally invoking nested functions

A nested function needs to be invoked using its path from the top-level root. Using the example application referenced above, you would enter the following to invoke the NestedFunction in the MyNestedApp application:

stackery local invoke -f MyNestedApp/NestedFunction -e <your-env-name>