Syntax Properties Return values Examples See also

AWS::CloudFormation::Stack

The AWS::CloudFormation::Stack type nests a stack as a resource in a top-level template.

You can add output values from a nested stack within the containing template. You use the GetAtt function with the nested stack's logical name and the name of the output value in the nested stack in the format Outputs.NestedStackOutputName.

Important

We strongly recommend that updates to nested stacks are run from the parent stack.

When you apply template changes to update a top-level stack, CloudFormation updates the top-level stack and initiates an update to its nested stacks. CloudFormation updates the resources of modified nested stacks, but doesn't update the resources of unmodified nested stacks. For more information, see CloudFormation stack updates.

Note

You must acknowledge IAM capabilities for nested stacks that contain IAM resources. Also, verify that you have cancel update stack permissions, which is required if an update rolls back. For more information about IAM and CloudFormation, see Controlling access with AWS Identity and Access Management.

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON


{
  "Type" : "AWS::CloudFormation::Stack",
  "Properties" : {
      "NotificationARNs" : [ String, ... ],
      "Parameters" : {Key : Value, ...},
      "Tags" : [ Tag, ... ],
      "TemplateURL" : String,
      "TimeoutInMinutes" : Integer
    }
}

YAML


Type: AWS::CloudFormation::Stack
Properties: 
  NotificationARNs: 
    - String
  Parameters: 
    Key : Value
  Tags: 
    - Tag
  TemplateURL: String
  TimeoutInMinutes: Integer

Properties

NotificationARNs

The Simple Notification Service (SNS) topic ARNs to publish stack related events. You can find your SNS topic ARNs using the SNS console or your Command Line Interface (CLI).

Required: No

Type: List of String

Maximum: 5

Update requires: No interruption

Parameters

The set value pairs that represent the parameters passed to CloudFormation when this nested stack is created. Each parameter has a name corresponding to a parameter defined in the embedded template and a value representing the value that you want to set for the parameter.

Note

If you use the Ref function to pass a parameter value to a nested stack, comma-delimited list parameters must be of type String. In other words, you can't pass values that are of type CommaDelimitedList to nested stacks.

Conditional. Required if the nested stack requires input parameters.

Whether an update causes interruptions depends on the resources that are being updated. An update never causes a nested stack to be replaced.

Required: Conditional

Type: Map of String

Update requires: No interruption

Tags

Key-value pairs to associate with this stack. AWS CloudFormation also propagates these tags to the resources created in the stack. A maximum number of 50 tags can be specified.

Required: No

Type: List of Tag

Maximum: 50

Update requires: No interruption

TemplateURL

Location of file containing the template body. The URL must point to a template (max size: 460,800 bytes) that's located in an Amazon S3 bucket. For more information, see Template anatomy.

Whether an update causes interruptions depends on the resources that are being updated. An update never causes a nested stack to be replaced.

Required: Yes

Type: String

Minimum: 1

Maximum: 1024

Update requires: No interruption

TimeoutInMinutes

The length of time, in minutes, that CloudFormation waits for the nested stack to reach the CREATE_COMPLETE state. The default is no timeout. When CloudFormation detects that the nested stack has reached the CREATE_COMPLETE state, it marks the nested stack resource as CREATE_COMPLETE in the parent stack and resumes creating the parent stack. If the timeout period expires before the nested stack reaches CREATE_COMPLETE, CloudFormation marks the nested stack as failed and rolls back both the nested stack and parent stack.

Updates are not supported.

Required: No

Type: Integer

Minimum: 1

Update requires: No interruption

Return values

Ref

When you pass the logical ID of this resource to the intrinsic Ref function, Ref returns the stack ID. For example:

arn:aws:cloudformation:us-east-2:123456789012:stack/mystack-mynestedstack-sggfrhxhum7w/f449b250-b969-11e0-a185-5081d0136786

For more information about using the Ref function, see Ref.

Examples

Specify stack parameters

The sample template EC2ChooseAMI.template contains the following Parameters section:

JSON


{
    "Parameters": {
        "InstanceType": {
            "Type": "String",
            "Default": "m1.small",
            "Description": "EC2 instance type, e.g. m1.small, m1.large, etc."
        },
        "WebServerPort": {
            "Type": "String",
            "Default": "80",
            "Description": "TCP/IP port of the web server"
        },
        "KeyName": {
            "Type": "String",
            "Description": "Name of an existing EC2 KeyPair to enable SSH access to the web server"
        }
    }
}

YAML


Parameters:
  InstanceType:
    Type: String
    Default: m1.small
    Description: 'EC2 instance type, e.g. m1.small, m1.large, etc.'
  WebServerPort:
    Type: String
    Default: '80'
    Description: TCP/IP port of the web server
  KeyName:
    Type: String
    Description: Name of an existing EC2 KeyPair to enable SSH access to the web server

Nested stack

You could use the following template to embed a stack (myStackWithParams) using the EC2ChooseAMI.template and use the Parameters property in the AWS::CloudFormation::Stack resource to specify an InstanceType and KeyName.

JSON


{
  "AWSTemplateFormatVersion" : "2010-09-09",
  "Resources" : {
    "myStackWithParams" : {
      "Type" : "AWS::CloudFormation::Stack",
      "Properties" : {
        "TemplateURL" : "https://s3.amazonaws.com/cloudformation-templates-us-east-2/EC2ChooseAMI.template",
        "Parameters" : {
          "InstanceType" : "t1.micro",
          "KeyName" : "mykey"
        }
      }
    }
  }
}

YAML


AWSTemplateFormatVersion: '2010-09-09'
Resources:
  myStackWithParams:
    Type: AWS::CloudFormation::Stack
    Properties:
      TemplateURL: https://s3.amazonaws.com/cloudformation-templates-us-east-2/EC2ChooseAMI.template
      Parameters:
        InstanceType: t1.micro
        KeyName: mykey