AWS AWSCloudFormation documentation change
Summary
Restructured documentation about nested stacks with improved examples, added detailed architecture example with Lambda/IAM resources, and expanded operational guidance
Security assessment
Added example includes IAM role configuration and mentions CAPABILITY_NAMED_IAM requirement for deployments - these are security-related best practices but don't address a specific vulnerability. New rollback guidance references IAM permissions but doesn't indicate a security flaw.
Diff
diff --git a/AWSCloudFormation/latest/UserGuide/using-cfn-nested-stacks.md b/AWSCloudFormation/latest/UserGuide/using-cfn-nested-stacks.md index b10e5caf7..a570144dc 100644 --- a//AWSCloudFormation/latest/UserGuide/using-cfn-nested-stacks.md +++ b//AWSCloudFormation/latest/UserGuide/using-cfn-nested-stacks.md @@ -3 +3 @@ -Splitting a CloudFormation templatePerforming stack operations on nested stacksRelated information +Before and after example of splitting a templateExample of a nested stack architecturePerforming stack operations on nested stacksRelated information @@ -5 +5 @@ Splitting a CloudFormation templatePerforming stack operations on nested stacksR -# Embed stacks within other stacks using nested stacks +# Split a template into reusable pieces using nested stacks @@ -7 +7 @@ Splitting a CloudFormation templatePerforming stack operations on nested stacksR -Nested stacks are stacks created as part of other stacks. You create a nested stack within another stack by using the [AWS::CloudFormation::Stack](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cloudformation-stack.html) resource. +As your infrastructure grows, you might find yourself repeatedly creating identical resource configurations across multiple templates. To avoid this redundancy, you can separate these common configurations into dedicated templates. Then, you can use the [AWS::CloudFormation::Stack](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cloudformation-stack.html) resource in other templates to reference these dedicated templates, creating nested stacks. @@ -9 +9 @@ Nested stacks are stacks created as part of other stacks. You create a nested st -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, suppose 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 can reference this template from within other templates that require the same load balancer configuration. @@ -11,3 +11 @@ As your infrastructure grows, common patterns can emerge in which you declare th -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: +Nested stacks can themselves contain other nested stacks, resulting in a hierarchy of stacks, as shown in the diagram below. The _root stack_ is the top-level stack to which all nested stacks ultimately belong. Each nested stack has an immediate parent stack. For the first level of nested stacks, the root stack is also the parent stack. @@ -28 +26,3 @@ Nested stacks can themselves contain other nested stacks, resulting in a hierarc - * Splitting a CloudFormation template + * Before and after example of splitting a template + + * Example of a nested stack architecture @@ -37 +37 @@ Nested stacks can themselves contain other nested stacks, resulting in a hierarc -## Splitting a CloudFormation template +## Before and after example of splitting a template @@ -39 +39 @@ Nested stacks can themselves contain other nested stacks, resulting in a hierarc -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. +This example demonstrates how you can 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. Each nested stack handles a specific set of related resources, making the overall structure more organized and easier to maintain. @@ -88,0 +89,131 @@ Before nesting stacks | After nesting stacks +## Example of a nested stack architecture + +This section demonstrates a nested stack architecture consisting of a top-level stack that references a nested stack. The nested stack deploys a Node.js Lambda function, receives a parameter value from the top-level stack, and returns an output that's exposed through the top-level stack. + +###### Topics + + * Step 1: Create a template for the nested stack on your local system + + * Step 2: Create a template for the top-level stack on your local system + + * Step 3: Package and deploy the templates + + + + +### Step 1: Create a template for the nested stack on your local system + +The following example shows the format of the nested stack template. + +#### YAML + + + AWSTemplateFormatVersion: 2010-09-09 + Description: Nested stack template for Lambda function deployment + Parameters: + MemorySize: + Type: Number + Default: 128 + MinValue: 128 + MaxValue: 10240 + Description: Lambda function memory allocation + Resources: + LambdaFunction: + Type: AWS::Lambda::Function + Properties: + FunctionName: !Sub "${AWS::StackName}-Function" + Runtime: nodejs18.x + Handler: index.handler + Role: !GetAtt LambdaExecutionRole.Arn + Code: + ZipFile: | + exports.handler = async (event) => { + return { + statusCode: 200, + body: JSON.stringify('Hello from Lambda!') + }; + }; + MemorySize: !Ref MemorySize + LambdaExecutionRole: + Type: AWS::IAM::Role + Properties: + AssumeRolePolicyDocument: + Version: '2012-10-17' + Statement: + - Effect: Allow + Principal: + Service: lambda.amazonaws.com + Action: sts:AssumeRole + ManagedPolicyArns: + - 'arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole' + Outputs: + LambdaArn: + Description: ARN of the created Lambda function + Value: !GetAtt LambdaFunction.Arn + +### Step 2: Create a template for the top-level stack on your local system + +The following example shows the format of the top-level stack template and the [AWS::CloudFormation::Stack](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cloudformation-stack.html) resource that references the stack you created in the previous step. + +#### YAML + + + AWSTemplateFormatVersion: 2010-09-09 + Description: Top-level stack template that deploys a nested stack + Resources: + NestedStack: + Type: AWS::CloudFormation::Stack + Properties: + TemplateURL: /path_to_template/nested-template.yaml + Parameters: + MemorySize: 256 + Outputs: + NestedStackLambdaArn: + Description: ARN of the Lambda function from nested stack + Value: !GetAtt NestedStack.Outputs.LambdaArn + +### Step 3: Package and deploy the templates + +###### Note + +When working with templates locally, the AWS CLI **package** command can help you prepare templates for deployment. It automatically handles the upload of local artifacts to Amazon S3 (including `TemplateURL`) and generates a new template file with updated references to these S3 locations. For more information, see [Upload local artifacts to an S3 bucket with the AWS CLI](./using-cfn-cli-package.html). + +Next, you can use the [package](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/package.html) command to upload the nested template to an Amazon S3 bucket. + + + aws cloudformation package \ + --s3-bucket amzn-s3-demo-bucket \ + --template /path_to_template/top-level-template.yaml \ + --output-template-file packaged-template.yaml \ + --output json + +The command generates a new template at the path specified by `--output-template-file`. It replaces the `TemplateURL` reference with the Amazon S3 location, as shown below. + +**Resulting template** + + + AWSTemplateFormatVersion: 2010-09-09 + Description: Top-level stack template that deploys a nested stack + Resources: + NestedStack: + Type: AWS::CloudFormation::Stack + Properties: + TemplateURL: https://s3.us-west-2.amazonaws.com/amzn-s3-demo-bucket/8b3bb7aa7abfc6e37e2d06b869484bed.template + Parameters: + MemorySize: 256 + Outputs: + NestedStackLambdaArn: + Description: ARN of the Lambda function from nested stack + Value: + Fn::GetAtt: + - NestedStack + - Outputs.LambdaArn + +After you run the **package** command, you can deploy the processed template using the [deploy](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deploy/) command. For nested stacks that contain IAM resources, you must acknowledge IAM capabilities by including the `--capabilities` option. + + + aws cloudformation deploy \ + --template-file packaged-template.yaml \ + --stack-name stack-name \ + --capabilities CAPABILITY_NAMED_IAM + @@ -91 +222,5 @@ Before nesting stacks | After nesting 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. +With 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. + +When you update a root stack, only nested stacks with template changes will be modified. All other nested stacks remain unchanged. + +Before proceeding with update operations, make sure that you have IAM permissions to cancel a stack update in case it rolls back. For more information, see [Control CloudFormation access with AWS Identity and Access Management](./control-access-with-iam.html). @@ -119,2 +253,0 @@ Nested stacks display **NESTED** above their stack name. - * [AWS CloudFormation template snippets](./quickref-cloudformation.html) - @@ -125 +258,3 @@ Nested stacks display **NESTED** above their stack name. - * [Continue rolling back an update](./using-cfn-updating-stacks-continueupdaterollback.html) + * [Continue rolling back from failed nested stack updates](./using-cfn-updating-stacks-continueupdaterollback.html#nested-stacks) + + * [Nested stacks rollback failure](./troubleshooting.html#troubleshooting-errors-nested-stacks-are-stuck)