Refactor CloudFormation Stack

#devops #aws #stacks #cloudformation

Reorganise resources in your CloudFormation stacks, preserving existing resource properties and data. Move resources between stacks, split large stacks into smaller ones, or combine multiple stacks into one.

How it works

Assess your current infrastructure – Review your existing CloudFormation stacks and resources to identify stack refactoring opportunities.
Plan your refactor – Define how resources should be organised. Consider your dependencies, naming conventions, and operational limits. These can affect the CloudFormation validation later.
Determine the destination stacks – Decide which stacks you will refactor resources into. You can move resources between at least 2 stacks (using the console), and a maximum of 5 stacks (using the AWS CLI). Resources can be moved between nested stacks.
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.
Create the stack refactor – Provide a list of stack names and templates that you want to refactor.
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.
If the validation succeeds, CloudFormation will generate a preview of the refactor actions that will occur during execution.
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.
Execute the refactor – After confirming the changes align with your refactoring goals, complete the stack refactor.
Monitor – Track the execution status to ensure the operation completes successfully.

Considerations

Stack refactoring is limited to reorganising existing resources. You cannot create or delete resources, modify resource configurations, or change or add new parameters, conditions, or mappings during refactoring. To make these changes, update your stacks first, and then perform the stack refactor.
You can't refactor the same resource into multiple stacks.
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. 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.

Prerequisites

To refactor stacks, you must have already created the revised templates.
Use the get-template 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 organisation.

Refactor stacks using AWS CLI

create-stack-refactor to validate and generate a preview of planned changes.
describe-stack-refactor to retrieve the status and details of a stack refactoring operation.
execute-stack-refactor to complete the validated stack refactoring operation.
list-stack-refactors to list all stack refactoring operations in your account with their current status and basic information.
list-stack-refactor-actions to show a preview of the specific actions CloudFormation will perform on each stack and resource during the refactor execution.

Use the create-stack-refactor 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

Note down the StackRefactorId

{
    "StackRefactorId": "9c384f70-4e07-4ed7-a65d-fee5eb430841"
}

If conflicts are detected during template validation, you can confirm in the next step. Then use the create-stack-refactor 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

Sample file:

[
    {
        "Source": {
            "StackName": "Stack1",
            "LogicalResourceId": "MySNSTopic"
        },
        "Destination": {
            "StackName": "Stack2",
            "LogicalResourceId": "MyLambdaSNSTopic"
        }
    }
]

Use the describe-stack-refactor 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

{
    "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"
}

Use the list-stack-refactor-actions command to preview the specific actions that will be performed.
aws cloudformation list-stack-refactor-actions --stack-refactor-id 9c384f70-4e07-4ed7-a65d-fee5eb430841

{
    "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",
            "Description": "Resource configuration changes will be validated during refactor execution.",
            "Detection": "AUTO",
            "TagResources": [
                {
                    "Key": "aws:cloudformation:stack-name",
                    "Value": "Stack2"
                },
                {
                    "Key": "aws:cloudformation:logical-id",
                    "Value": "MyFunction"
                },
                {
                    "Key": "aws:cloudformation:stack-id",
                    "Value": "arn:aws:cloudformation:us-east-1:123456789012:stack/Stack2/5da91650-94b1-11f0-81cf-0a23500e151b"
                }
            ],
            "UntagResources": [
                "aws:cloudformation:stack-name",
                "aws:cloudformation:logical-id",
                "aws:cloudformation:stack-id"
            ],
            "ResourceMapping": {
                "Source": {
                    "StackName": "arn:aws:cloudformation:us-east-1:123456789012:stack/Stack1/3e6a1ff0-94b1-11f0-aa6f-0a88d2e03acf",
                    "LogicalResourceId": "MyFunction"
                },
                "Destination": {
                    "StackName": "arn:aws:cloudformation:us-east-1:123456789012:stack/Stack2/5da91650-94b1-11f0-81cf-0a23500e151b",
                    "LogicalResourceId": "MyFunction"
                }
            }
        }
    ]
}

After reviewing and confirming your changes, use the execute-stack-refactor command to complete the stack refactoring operation.
aws cloudformation execute-stack-refactor --stack-refactor-id 9c384f70-4e07-4ed7-a65d-fee5eb430841
Use the describe-stack-refactor command to monitor the execution status.
aws cloudformation describe-stack-refactor --stack-refactor-id 9c384f70-4e07-4ed7-a65d-fee5eb430841

{
    "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": "SUCCEEDED",
    "Status": "COMPLETE"
}

Ref: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stack-refactoring.html

Debug School

Refactor CloudFormation Stack

How it works

Considerations

Prerequisites

Refactor stacks using AWS CLI

Top comments (0)