Import and export virtual machine (VM) images with EC2 Image Builder - EC2 Image Builder
Import a VM into Image Builder (Amazon CLI)Distribute VM disks from your image build (Amazon CLI)
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Import and export virtual machine (VM) images with EC2 Image Builder

When you export your VM from its virtualization environment, that process creates a set of one or more disk container files that act as snapshots of your VM’s environment, settings, and data. You can use these files to import your VM, and use it as the base image for your image recipes.

Image Builder supports the following file formats for your VM disk containers:

  • Open Virtualization Archive (OVA)

  • Virtual Machine Disk (VMDK)

  • Virtual Hard Disk (VHD/VHDX)

  • Raw

The import uses the disks to create an Amazon Machine Image (AMI) and an Image Builder image resource, either of which can serve as the base image for your custom image recipe. The VM disks must be stored in S3 buckets for the import. Alternatively, you can import from an existing EBS snapshot.

In the Image Builder console, you can import the image directly, and then use the output image or AMI in your recipes, or you can specify import parameters when you are creating your recipe or recipe version. For more information about importing directly, see Import a VM (console). For more information about importing as part of your image recipe, see VM import configuration.

Import a VM into Image Builder (Amazon CLI)

To import a VM from disks into an AMI and create an Image Builder image resource that you can reference right away, follow these steps from the Amazon CLI:

  1. Initiate a VM import, with the Amazon EC2 VM Import/Export import-image command in the Amazon CLI. Make note of the task ID that is returned in the command response. You'll need it for the next step. For more information, see Importing a VM as an image using VM Import/Export in the VM Import/Export User Guide.

  2. Create a CLI input JSON file

    To streamline the Image Builder import-vm-image command that is used in the Amazon CLI, we create a JSON file that contains all of the import configuration that we want to pass into the command.

    Note

    The naming convention for the data values in the JSON file follows the pattern that is specified for the Image Builder API action request parameters. To review the API command request parameters, see the ImportVmImage command in the EC2 Image Builder API Reference.

    To provide the data values as command line parameters, refer to the parameter names specified in the Amazon CLI Command Reference. to the Image Builder import-vm-image command as options.

    Here is a summary of the parameters that we specify in this example:

    • name (string, required) – The name for the Image Builder image resource to create as output from the import.

    • semanticVersion (string, required) – The semantic version for the output image that specifies the version in the following format, with numeric values in each position to indicate a specific version: <major>.<minor>.<patch>. For example, 1.0.0. To learn more about semantic versioning for Image Builder resources, see Semantic versioning.

    • description (string) – The description of the image recipe.

    • platform (string, required) – The operating system platform for the imported VM.

    • vmImportTaskId (string, required) – The ImportTaskId (Amazon CLI) from the Amazon EC2 VM import process. Image Builder monitors the import process to pull in the AMI that it creates and build an Image Builder image resource that can be used in recipes right away.

    • clientToken (string, required) – A unique, case-sensitive identifier you provide to ensure idempotency of the request. For more information, see Ensuring idempotency in the Amazon EC2 API Reference.

    • tags (string map) – Tags are key-value pairs that are attached to the import resources. Up to 50 key-value pairs are allowed.

    Save the file as import-vm-image.json, to use in the Image Builder import-vm-image command.

    {
    "name": "example-request",
    "semanticVersion": "1.0.0",
    "description": "vm-import-test",
    "platform": "Linux",
    "vmImportTaskId": "import-ami-01ab234567890cd1e",
    "clientToken": "asz1231231234cs3z",
    "tags": {
    	"Usage": "VMIE"
    }
}
  3. Import the image

    Run the import-vm-image command, with the file that you created as input:

    aws imagebuilder import-vm-image --cli-input-json file://import-vm-image.json
    Note

    • You must include the file:// notation at the beginning of the JSON file path.

    • The path for the JSON file should follow the appropriate convention for the base operating system where you are running the command. For example, Windows uses the backslash (\) to refer to the directory path, and Linux uses the forward slash (/).

Distribute VM disks from your image build (Amazon CLI)

You can set up distribution of supported VM disk format files to S3 buckets in target Regions as part of your regular image build process, using Image Builder distribution configurations in the Amazon CLI. For more information, see Create distribution settings for output VM disks (Amazon CLI).