Distribute an Amazon Machine Image to another AWS Account using AWS Application Migration Service Post-launch automation

Many customers migrating their workloads to AWS using AWS Application Migration Service want to use different AWS accounts to support their company’s governance and security needs. Customers may also choose to use Infrastructure As Code (IaC) templates using AWS CloudFormation or Terraform with Application Migration Service to deploy source servers to different AWS Accounts. To utilize multiple accounts and utilize IaC, a source server can be migrated using the Application Migration Service, and then an Amazon Machine Image (AMI) can be created from the migrated server for launching additional instances. This saves on the replication time, and is an easy way to launch the same application in multiple accounts. Performing this action at scale with many instances requires automation as the multiple manual steps need to be consistently performed to avoid any potential errors. AWS Key Management Serivce (AWS KMS) is used for encryption of Amazon Elastic Block Store (Amazon EBS) volumes and this adds additional steps to the AMI sharing process. Customers can additionally choose to copy an AMI to another AWS account for the purpose of AMI ownership, AMI lifecycle management and reuse of that AMI for multiple launches.

In this blog post I show how to use Application Migration Service Post-launch settings to start an Automation Document, a capability of AWS Systems Manager, to create, share, copy and clean-up an AMI as part of the migration process.

Solution Overview

The following diagram and steps are an overview of how an AMI is shared and copied by the Automation Document. Follow the implementation steps to configure the automation. You can download the Automation Document code from github.

Diagram of what happens during the image distribution automation

Figure 1: Diagram of automation steps

Explanation of the key steps from the diagram:

Application Migration Service launches a cutover instance from source server. The Amazon EBS encryption settings need to use a Custom KMS key. See Prerequisites section.
MGN Post-launch settings are configured to run a Custom post-launch action. The Automation Document assumes an AWS Identity and Access Management (IAM) role which it will use to perform actions. See Prerequisites section.
Automation Document creates AMI from launched cutover instance.
Automation Document shares the AMI with the Target AWS account.
Automation Document shares each EBS Snapshot used by the AMI with the Target AWS account.
(Optional) Automation Document runs the aws:executeScript action to assume an IAM role in the Target AWS account and run the CopyImage API to copy the AMI and snapshots to be owned by the Target AWS account. See Prerequisites section.
(Optional) Automation Document terminates the original cutover instance, AMI and EBS Snapshots.

Prerequisites

Custom KMS Key for Application Migration Service EBS volumes

For other AWS accounts to be able to access snapshots from launched instances Amazon EBS encryption settings need to use a Custom key which grants the other AWS account access to use the key. Create a KMS key with the following example policy to grant access for other accounts within an AWS Organization to use the key.

{ 
   "Sid": "Allow use of the KMS key for organization",
   "Effect": "Allow",
   "Principal": {
      "AWS": "*"
   },
   "Action": [
      "kms:Decrypt",
      "kms:DescribeKey",
      "kms:Encrypt",
      "kms:ReEncrypt*",
      "kms:CreateGrant",
      "kms:GetKeyPolicy"
   ],
   "Resource": "*",
   "Condition": {
      "StringEquals": {
         "aws:PrincipalOrgID": "o-xxxxxxxxxxx"
      }
   }
},
{
   "Sid": "Allow administration of the KMS key by account"
   "Effect": "Allow",
   "Principal": {
      "AWS": "arn:aws:iam:: MGNAWSACCOUNT:root"
   },
   "Action": "kms:*",
   "Resource": "*"
}

Note: It is important the aws:PrincipalOrgID condition is added to prevent accounts not part of your organization from using the key. This key should only be used for this AMI sharing purpose

After creating the KMS key ensure Amazon EBS encryption settings within the Application Migration Service are set to use the new KMS key.

IAM Role for SSM

The Automation Document requires an IAM role with permission to perform the required tasks. Create an IAM role with the following settings:

Trust Policy

{
   "Version": "2012-10-17",
   "Statement": [
   {
      "Effect": "Allow",
      "Principal": {
         "Service": "ssm.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
         "StringEquals": {
            "aws:SourceAccount": "MGNAWSACCOUNT"
         },
         "ArnLike": {
            "aws:SourceArn": "arn:aws:ssm:*:MGNAWSACCOUNT:automation-execution/*"
         }
      }
   }
   ]
}

Permissions

Note: The sts:AssumeRole permission is only required if using the copy AMI to another account functionality.

{
   "Version": "2012-10-17",
   "Statement": [
   {
      "Effect": "Allow",
      "Action": [
         "sts:AssumeRole"
      ],
      "Resource": "arn:aws:iam::*:role/<CrossAccountImageCopyRole>"
   },
   {
      "Effect": "Allow",
      "Action": [
         "ec2:CreateImage",
         "ec2:DescribeImages",
         "ec2:ModifyImageAttribute",
         "ec2:ModifySnapshotAttribute",
         "ec2:TerminateInstances",
         "ec2:DeregisterImage",
         "ec2:DeleteSnapshot"
      ],
      "Resource": [
         "*"
      ]
   },
   {
      "Effect": "Allow",
      "Action": [
         "kms:ReEncrypt*"
      ],
      "Resource": [
         "<ARN of KMS Key used by MGN>"
      ]
   }
   ]
}

IAM Role in Target Account

The CopyImage API is executed by a role within the AWS Account the AMI is to copied into. The Automation Document assumes the following role to execute the CopyImage API and check the status of the image creation.

Trust Policy

{
   "Version": "2012-10-17",
   "Statement": [
   {
      "Effect": "Allow",
      "Principal": {
         "AWS": "arn:aws:iam::<MGNAccountId>:role/<SSMRoleName>"
      },
      "Action": "sts:AssumeRole"
   },
   "Condition": {
      "StringEquals": {
         "aws:SourceAccount": "MGNAWSACCOUNT"
      }
   }
   ]
}

Permissions

{
   "Version": "2012-10-17",
   "Statement": [
   {
      "Sid": "AccessForKMSActions",
      "Effect": "Allow",
      "Action": [
         "kms:DescribeKey",
         "kms:ReEncrypt*",
         "kms:CreateGrant",
         "kms:Decrypt"
      ],
      "Resource": [
         "<KMSKeyInMGNAccount>"
      ]
   },
   {
      "Sid": "AccessForEC2Actions",
      "Effect": "Allow",
      "Action": [
         "ec2:CopyImage",
         "ec2:DescribeImages"
      ],
      "Resource": [
         "*"
      ]
   }
   ]
}

Implementation

Use the following steps to create the Automation Document and configure the Application Migration Service to run the document as a post-launch custom action:

Create Automation Document

On the AWS Systems Manager console, choose Documents in the navigation pane.
Choose Create document Automation.
Select the pencil icon and enter a document name.
Choose Code to move to code input screen.
Copy contents from distributeami.yml
Choose Create runbook.

The Automation Document is visible in documents “Owned by me”. This document is only available to your AWS Account.

Activate Post-launch custom action

Post-launch settings must first be activated on the Post-launch template page.

On the Application Migration Service console, choose Source Servers in the navigation pane.
Choose the source server to configure with post-launch settings (Can also be configured as a Post-launch settings template to be applied to all newly added servers).
Choose Post-launch settings.
Choose Create action.
Provide a name for the Action and ensure Activate this action is checked.
For Systems Manager document name choose the Automation Document you created.
Ensure the Order number is correct. It is likely AMI creation and sharing is the last post-launch action to be completed so it should have the highest order number.
Enter values for the Action Parameters. Some parameters are optional depending if copying the AMI into another AWS account is required.
Choose Add action. This step creates the action.

When you launch a test or cutover instance from the Application Migration Service console, the service will automatically execute the actions defined in the specific server’s post-launch actions settings. You can track the progress of these actions from the source server’s migration dashboard page.

Conclusion

With AWS Application Migration Service post-launch settings Automation Documents, a capability of AWS Systems Manager, can be triggered to automate actions needed in the migration process. You can automate the creation, sharing and copying of Amazon Machine Images with other AWS accounts for distributed ownership and operations of migrated machines or to use the AMI’s within Infrastructure as Code templates. See other Predefined post-launch actions which can be used by the Application Migration Service or create your own custom Automation Documents

Get started with AWS Application Migration Service

About the Author

Peter Giuliano is a Senior Migration Solution Architect at AWS with 18 years experience working with OnPremise and Cloud infrastructure. At AWS he helps enterprise customers plan and execute large scale migrations to the Cloud making sure customer experiences and lessons are shared. Outside of work Peter is a keen runner and enjoys traveling to new places.

AWS Cloud Operations & Migrations Blog