How do I use VM Import/Export to export a VM based on my Amazon Machine Image (AMI)?

Short description

You can use the AWS Command Line Interface (AWS CLI) to start an image export task using VM Import/Export. Then, a copy of your Amazon Machine Image (AMI) is exported as a VM file and written to an Amazon Simple Storage Service (Amazon S3) bucket. You can use the exported VM to deploy a new, standardized instance in your on-site virtualization environment. You can export most AMIs to Citrix Xen, Microsoft Hyper-V, or VMware vSphere.

Note: If you receive errors when running AWS CLI commands, make sure that you’re using the most recent version of the AWS CLI.

Before starting the following resolution steps, do the following:

• Review the considerations and limitations of VM Import/Export to verify that VM Import/Export supports your AMI.
• If you sign in as an AWS Identity and Access Management (IAM) user to use VM Import/Export, be sure to have the required permissions for IAM users in your policy.

Resolution

1.    Create an Amazon Elastic Block Store (Amazon EBS) backed AMI from the EC2 instance that you want to export.

For Linux, see Create an Amazon EBS-backed Linux AMI.

For Windows, see Create a custom Windows AMI.

2.    Install the AWS CLI on a client machine and configure it with the AWS credentials generated for your IAM user.

3.    Create a new S3 bucket in the same AWS Region as the AMI that you plan to export.

4.     Create the required service role. As a prerequisite, make sure to enable AWS Security Token Service (AWS STS) in the Region where you're using VM Import/Export.

To create the service role, first create a file named trust-policy.json on your computer and then add the following policy to the file:

{
   "Version": "2012-10-17",
   "Statement": [
      {
         "Effect": "Allow",
         "Principal": { "Service": "vmie.amazonaws.com" },
         "Action": "sts:AssumeRole",
         "Condition": {
            "StringEquals":{
               "sts:Externalid": "vmimport"
            }
         }
      }
   ]
}

Run the create-role command to create a role named vmimport using the trust-policy.json file to grant VM Import/Export access to the role:

aws iam create-role --role-name vmimport --assume-role-policy-document "file://C:\import\trust-policy.json"

Note: In the preceding example, make sure to specify the full path to the location of the trust-policy.json file that you created. Be sure to include the file:// prefix.

Create another file named role-policy.json on your computer and add the following policy to the file. Replace my-export-bucket with your S3 bucket name.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetBucketLocation",
                "s3:GetObject",
                "s3:ListBucket",
                "s3:PutObject",
                "s3:GetBucketAcl"
            ],
            "Resource": [
                "arn:aws:s3:::my-export-bucket",
                "arn:aws:s3:::my-export-bucket/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "ec2:ModifySnapshotAttribute",
                "ec2:CopySnapshot",
                "ec2:RegisterImage",
                "ec2:Describe*"
            ],
            "Resource": "*"
        }
    ]
}

Use the put-role-policy command to attach the role-policy.json policy to the vmimport role that you created previously:

aws iam put-role-policy --role-name vmimport --policy-name vmimport --policy-document "file://C:\import\role-policy.json"

In the preceding example, be sure to specify the full path to the location of the role-policy.json file.

Note: Future updates to VM Import/Export might require additional permissions in the vmimport role. Refer to the example policy in the required service role documentation for the most up-to-date example of the required permissions.

5.    From the client machine where you installed the AWS CLI, run the AWS CLI command export-image to start the export image task:

aws ec2 export-image --image-id ami-id --disk-image-format VMDK --s3-export-location S3Bucket=my-export-bucket,S3Prefix=exports/

Note: In the preceding example, replace ami-id with your AMI ID. Choose the desired disk image format (VMDK, RAW or VHD). Replace my-export-bucket with your S3 bucket name. The exported file is written to your specified S3 bucket using the S3 key prefixexport-ami-id.format (for example, my-export-bucket/exports/export-ami-1234567890abcdef0.vmdk). You can add a prefix to the exported file.

If the request is successful, the export-image command output returns details about the task including an export image task ID, as shown in the following example:

{
    "DiskImageFormat": "vmdk",
    "ExportImageTaskId": "export-ami-1234567890abcdef0"
    "ImageId": "ami-1234567890abcdef1",
    "RoleName": "vmimport",
    "Progress": "0",
    "S3ExportLocation": {
        "S3Bucket": "my-export-bucket",
        "S3Prefix": "exports/"
    },
    "Status": "active",
    "StatusMessage": "validating"
}

6.    To check the status of your export image task, run the AWS CLI command describe-export-image-tasks.

Example

aws ec2 describe-export-image-tasks --export-image-task-id export-ami-id

Note: In the preceding example, replace export-ami-id with the export image task ID from the export-image command output.

The describe-export-image-tasks command output returns details about the progress and overall status of the task. The following example output is for an export image task that is in an active status and in progress:

{
    "ExportImageTasks": [
        {
            "ExportImageTaskId": "export-ami-1234567890abcdef0"
            "Progress": "21",
            "S3ExportLocation": {
                "S3Bucket": "my-export-bucket",
                "S3Prefix": "exports/"
            },
            "Status": "active",
            "StatusMessage": "updating"
        }
    ]
}

7.    When the status of your export image task changes to "completed", the exported file is ready in your S3 bucket as an object. The following example output shows a completed export image task. The resulting exported file in Amazon S3 is my-export-bucket/exports/export-ami-1234567890abcdef0.vmdk.

{
    "ExportImageTasks": [
        {
            "ExportImageTaskId": "export-ami-1234567890abcdef0"
            "S3ExportLocation": {
                "S3Bucket": "my-export-bucket",
                "S3Prefix": "exports/"
            },
            "Status": "completed"
        }
    ]
}

8.    Access your S3 bucket using the Amazon S3 console to locate and download the object.

Related information

Export from an AMI

Creating an IAM user in your AWS account

Programmatic access (access key ID and secret access key)

Amazon Machine Images (AMI)

Troubleshooting VM Import/Export