AWS AWSCloudFormation documentation change
Summary
Major restructuring of stack refactoring documentation including expanded CLI instructions, renamed sections ('limitations' to 'considerations'), added resource limitations list, and detailed workflow steps
Security assessment
The changes primarily improve operational documentation about stack refactoring processes. While they mention limitations like stack policy incompatibility and empty stack prevention, these are operational constraints rather than security vulnerability fixes. No CVE references or explicit security advisories are present.
Diff
diff --git a/AWSCloudFormation/latest/UserGuide/stack-refactoring.md b/AWSCloudFormation/latest/UserGuide/stack-refactoring.md index ae719984a..c0ce1f840 100644 --- a//AWSCloudFormation/latest/UserGuide/stack-refactoring.md +++ b//AWSCloudFormation/latest/UserGuide/stack-refactoring.md @@ -5 +5 @@ -How stack refactoring worksStack refactoring limitationsRefactoring a stack using the AWS Command Line Interface +How stack refactoring worksStack refactoring considerationsAWS CLI commandsRefactor a stack using the AWS CLIResource limitations @@ -9 +9,16 @@ How stack refactoring worksStack refactoring limitationsRefactoring a stack usin -Stack refactoring simplifies reorganizing the resources in your CloudFormation stacks while still preserving the existing resource properties and data. With stack refactoring, you can move resources between stacks, split monolithic stacks into smaller components, or consolidate multiple stacks into one. +With stack refactoring, you can reorganize resources in your CloudFormation stacks while preserving existing resource properties and data. You can move resources between stacks, split large stacks into smaller ones, or combine multiple stacks into one stack. + +###### Topics + + * How stack refactoring works + + * Stack refactoring considerations + + * AWS CLI commands for stack refactoring + + * Refactor a stack using the AWS CLI + + * Resource limitations + + + @@ -13 +28 @@ Stack refactoring simplifies reorganizing the resources in your CloudFormation s -Take the steps below into consideration when planning your stack refactor: +Refactoring stacks involves these phases: @@ -15 +30 @@ Take the steps below into consideration when planning your stack refactor: - 1. **Assess your current infrastructure:** Review your existing CloudFormation stacks and resources to identify stack refactoring opportunities. + 1. Assess your current infrastructure – Review your existing CloudFormation stacks and resources to identify stack refactoring opportunities. @@ -17 +32 @@ Take the steps below into consideration when planning your stack refactor: - 2. **Plan your refactor:** Define how resource should be organized. Consider your dependencies, naming conventions, and operational limits. These can affect the CloudFormation validation later. + 2. Plan your refactor – Define how resources should be organized. Consider your dependencies, naming conventions, and operational limits. These can affect the CloudFormation validation later. @@ -19 +34 @@ Take the steps below into consideration when planning your stack refactor: -Determine the number of destination stacks you will be refactoring resources into. You can move resource between at least 2 stacks, and a maximum of 5 stacks. Resources can be moved between nested stacks. + 3. Determine the destination stacks – Decide which stacks you will refactor resources into. You can move resources between at least 2 stacks, and a maximum of 5 stacks. Resources can be moved between nested stacks. @@ -21 +36 @@ Determine the number of destination stacks you will be refactoring resources int - 3. **Update your templates:** Modify your CloudFormation templates to reflect the planned change, such as moving resource definitions between templates. You can rename logical IDs during refactoring. + 4. Update your templates – Change your CloudFormation templates to reflect the planned change, such as moving resource definitions between templates. You can rename logical IDs during this process. @@ -23 +38 @@ Determine the number of destination stacks you will be refactoring resources int - 4. **Create the stack refactor:** Provide a list of stack names and templates that you want to refactor. + 5. Create the stack refactor – Provide a list of stack names and templates that you want to refactor. @@ -25 +40 @@ Determine the number of destination stacks you will be refactoring resources int - 5. **Review the refactor impact on your infrastructure and resolve any conflicts:** CloudFormation validates the templates you provide and checks cross-stack dependencies, resource types with tag update problems, and resource logical ID conflicts. + 6. Review the refactor impact and resolve any conflicts – CloudFormation validates the templates you provide and checks cross-stack dependencies, resource types with tag update problems, and resource logical ID conflicts. @@ -27 +42 @@ Determine the number of destination stacks you will be refactoring resources int -If the validation succeeds, CloudFormation will generate a preview of the refactor actions that will happen after executing the refactor. +If the validation succeeds, CloudFormation will generate a preview of the refactor actions that will occur during execution. @@ -29 +44 @@ If the validation succeeds, CloudFormation will generate a preview of the refact -If the validation fails, you can retry after resolving the issues found. If there are conflicts, you will need to provide a resource logical ID mapping that shows the source and destination of the resource in conflict. +If the validation fails, resolve the identified issues and retry. For conflicts, provide a resource logical ID mapping that shows the source and destination of the conflicting resources. @@ -31 +46 @@ If the validation fails, you can retry after resolving the issues found. If ther - 6. **Execute the refactor:** After confirming the changes align with how you want to refactor your stacks, execute the stack refactor. + 7. Execute the refactor – After confirming the changes align with your refactoring goals, complete the stack refactor. @@ -33 +48 @@ If the validation fails, you can retry after resolving the issues found. If ther - 7. **Monitor:** See the `ExecutionStatus` for the status of the stack refactor to make sure it's successful. + 8. Monitor – Track the execution status to ensure the operation completes successfully. @@ -38 +53 @@ If the validation fails, you can retry after resolving the issues found. If ther -## Stack refactoring limitations +## Stack refactoring considerations @@ -40 +55 @@ If the validation fails, you can retry after resolving the issues found. If ther -Consider the following limitations when planning your stack refactor: +As you refactor your stacks, keep the following in mind: @@ -44 +59 @@ Consider the following limitations when planning your stack refactor: - * You can't change or add new parameters, conditions, or mappings during a stack refactor. A potential workaround is to update your stack before performing the refactor. + * You can't change or add new parameters, conditions, or mappings during a stack refactor. A possible workaround is to update your stack before performing the refactor. @@ -48 +63,177 @@ Consider the following limitations when planning your stack refactor: - * You cannot refactor a resource to a new stack if that stack uses certain pseudo parameters (Example: `AWS::StackName`). + * You can't refactor resources that refer to pseudo parameters whose values differ between the source and destination stacks, such as `AWS::StackName`. + + * CloudFormation doesn't support empty stacks. If refactoring would leave a stack with no resources, you must first add at least one resource to that stack before you run [create-stack-refactor](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/create-stack-refactor.html). This can be a simple resource like `AWS::SNS::Topic` or `AWS::CloudFormation::WaitCondition`. For example: + + Resources: + MySimpleSNSTopic: + Type: AWS::SNS::Topic + Properties: + DisplayName: MySimpleTopic + + * Stack refactor doesn't support stacks that have stack policies attached, regardless of what the policies allow or deny. + + + + +## AWS CLI commands for stack refactoring + +The AWS CLI commands for stack refactoring include: + + * [create-stack-refactor](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/create-stack-refactor.html) to validate and generate a preview of planned changes. + + * [describe-stack-refactor](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-stack-refactor.html) to retrieve the status and details of a stack refactoring operation. + + * [execute-stack-refactor](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/execute-stack-refactor.html) to complete the validated stack refactoring operation. + + * [get-template](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/get-template.html) to retrieve the template for an existing stack. + + * [list-stack-refactors](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-stack-refactors.html) to list all stack refactoring operations in your account with their current status and basic information. + + * [list-stack-refactor-actions](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-stack-refactor-actions.html) to show a preview of the specific actions CloudFormation will perform on each stack and resource during the refactor execution. + + + + +## Refactor a stack using the AWS CLI + +Use the following procedure to refactor a stack using the AWS CLI. + + 1. Use the [get-template](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/get-template.html) command to retrieve the CloudFormation templates for the stacks that you want to refactor. + + aws cloudformation get-template --stack-name Stack1 + +When you have the templates, use the integrated development environment (IDE) of your choice to update them to use the desired structure and resource organization. + + 2. Use the [create-stack-refactor](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/create-stack-refactor.html) command and provide the stack names and updated templates for the stacks to refactor. Include the `--enable-stack-creation` option to allow CloudFormation to create new stacks if they don't already exist. + + aws cloudformation create-stack-refactor \ + --stack-definitions \ + StackName=Stack1,TemplateBody@=file://template1-updated.yaml \ + StackName=Stack2,TemplateBody@=file://template2-updated.yaml \ + --enable-stack-creation + +The command returns a `StackRefactorId` that you'll use in later steps. + + { + "StackRefactorId": "9c384f70-4e07-4ed7-a65d-fee5eb430841" + } + +If conflicts are detected during template validation (which you can confirm in the next step), use the [create-stack-refactor](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/create-stack-refactor.html) command with the `--resource-mappings` option. + + aws cloudformation create-stack-refactor \ + --stack-definitions \ + StackName=Stack1,TemplateBody@=file://template1-updated.yaml \ + StackName=Stack2,TemplateBody@=file://template2-updated.yaml \ + --enable-stack-creation \ + --resource-mappings file://resource-mapping.json + +The following is an example `resource-mapping.json` file. + + [ + { + "Source": { + "StackName": "Stack1", + "LogicalResourceId": "MySNSTopic" + }, + "Destination": { + "StackName": "Stack2", + "LogicalResourceId": "MyLambdaSNSTopic" + } + } + ] + + 3. Use the [describe-stack-refactor](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-stack-refactor.html) command to make sure the `Status` is `CREATE_COMPLETE`. This verifies that the validation is complete. + + aws cloudformation describe-stack-refactor \ + --stack-refactor-id 9c384f70-4e07-4ed7-a65d-fee5eb430841 + +Example output: + + { + "StackRefactorId": "9c384f70-4e07-4ed7-a65d-fee5eb430841", + "StackIds": [ + "arn:aws:cloudformation:us-east-1:123456789012:stack/Stack1/3e6a1ff0-94b1-11f0-aa6f-0a88d2e03acf", + "arn:aws:cloudformation:us-east-1:123456789012:stack/Stack2/5da91650-94b1-11f0-81cf-0a23500e151b" + ], + "ExecutionStatus": "AVAILABLE", + "Status": "CREATE_COMPLETE" + } + + 4. Use the [list-stack-refactor-actions](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-stack-refactor-actions.html) command to preview the specific actions that will be performed. + + aws cloudformation list-stack-refactor-actions \ + --stack-refactor-id 9c384f70-4e07-4ed7-a65d-fee5eb430841 + +Example output: + + { + "StackRefactorActions": [ + { + "Action": "MOVE", + "Entity": "RESOURCE", + "PhysicalResourceId": "MyTestLambdaRole", + "Description": "No configuration changes detected.", + "Detection": "AUTO", + "TagResources": [], + "UntagResources": [], + "ResourceMapping": { + "Source": { + "StackName": "arn:aws:cloudformation:us-east-1:123456789012:stack/Stack1/3e6a1ff0-94b1-11f0-aa6f-0a88d2e03acf", + "LogicalResourceId": "MyLambdaRole" + }, + "Destination": { + "StackName": "arn:aws:cloudformation:us-east-1:123456789012:stack/Stack2/5da91650-94b1-11f0-81cf-0a23500e151b", + "LogicalResourceId": "MyLambdaRole" + } + } + }, + { + "Action": "MOVE", + "Entity": "RESOURCE", + "PhysicalResourceId": "MyTestFunction",