Menu
Amazon Elastic Compute Cloud
CLI Reference (API Version 2015-10-01)

ec2-import-instance

Description

Creates an import instance task using metadata from the specified disk image, and imports the image to Amazon EC2. For more information about prerequisites for importing an instance, see VM Import/Export Prerequisites and Step 2: Prepare Your VM in the Amazon EC2 User Guide for Linux Instances. For more information about importing an instance, see Step 4: Importing Your VM into Amazon EC2.

If the upload task doesn't complete, use ec2-resume-import to resume the import from where it was interrupted.

Note

The ec2-import-instance command does not support Amazon Simple Storage Service (Amazon S3) authentication using AWS Security Token Service (AWS STS) credentials (-t --security-token option).

The short version of this command is ec2iin.

Syntax

ec2-import-instance -t instance_type [-g group] -f file_format -a architecture [-p platform_name] -b s3_bucket_name [-o owner] -w secret_key [--prefix prefix] [--manifest-url url] [-s volume_size ] [-z availability_zone] [-d description] [--user-data user_data] [--user-data-file disk_image_filename] [--subnet subnet_id] [--private-ip-address ip_address] [--monitor] [--instance-initiated-shutdown-behavior behavior] [--x days] [--ignore-region-affinity] [--dry-run] [--no-upload] [--dont-verify-format]

Options

NameDescription

-t, --instance-type instance_type

The type of instance to be launched. For more information, see Instance Types in the Amazon EC2 User Guide for Linux Instances. For more information about the Linux instance types you can import, see Prerequisites in the Amazon EC2 User Guide for Linux Instances.

Type: String

Default: m1.small

Required: Yes

Example: -t m1.small

Note

The -a option is only honored if the -t option is passed. If the -t option is not passed, then -a is treated as i386. If the -t option is not passed, the instance type defaults to m1.small.

-g, --group group

The security group (or groups if specified multiple times) within which the instances should be run. Determines the ingress firewall rules that are applied to the launched instances. Defaults to your default security group if the -g option is not supplied. This is not supported for VMs imported into a VPC, which are assigned the default security group. After a VM is imported into a VPC, you can specify another security group using the AWS Management Console.

Type: String

Default: Your default security group

Required: No

Example: -g myGroup

-f, --format file_format

The file format of the disk image.

Type: String

Valid values: VMDK | RAW | VHD

Default: None

Required: Yes

Example: -f VMDK

-a, --architecture architecture

The architecture of the image. Using this option ensures that your image is imported as the expected instance type.

Type: String

Valid values: i386 | x86_64

Default: i386

Required: Yes

Condition: Required if instance type is specified; otherwise defaults to i386.

Note

The -a option is only honored if the -t option is passed. If the -t option is not passed, then -a is treated as i386. If the -t option is not passed, the instance type defaults to m1.small.

Example: -a i386

-p, --platform platform_name

The operating system of the instance.

Type: String

Default: None

Valid value: Windows | Linux

Required: No

-b, --bucket s3_bucket_name

The Amazon S3 destination bucket for the manifest.

Type: String

Default: None

Required: Conditional

Condition: The --manifest-url parameter is not specified.

Example: myawsbucket

-o, --owner-akid access_key_id

The access key ID of the bucket owner. Before you specify a value for this option, review and follow the guidance in Best Practices for Managing AWS Access Keys.

Type: String

Default: None

Required: Yes

Example: AKIAIOSFODNN7EXAMPLE

-w, --owner-sak secret_access_key

The secret access key of the bucket owner. Before you specify a value for this option, review and follow the guidance in Best Practices for Managing AWS Access Keys.

Type: String

Default: None

Required: Yes

Example: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

--prefix prefix

The prefix for the manifest file and disk image file parts within the Amazon S3 bucket.

Type: String

Default: None

Required: No

Example: --prefix MyDiskParts

--manifest-url url

The URL for an existing import manifest file already uploaded to Amazon S3. For information about the import manifest, see VM Import Manifest.

Type: String

Default: None. This option can't be specified if the --bucket option is present.

Required: No

Example: my-ami.manifest.xml

-s, --volume-size volume_size

The size of the Amazon EBS volume, in GiB, that will hold the converted image. If not specified, Amazon EC2 calculates the value using the disk image file.

Type: String

Default: None

Required: No

Example: -s 30

-z, --availability-zone availability_zone

The Availability Zone for the converted VM.

Type: String

Valid values: Use ec2-describe-availability-zones for a list of values

Default: None

Required: No

Example: -z us-east-1a

-d, --description description

An optional, free-form comment returned verbatim during subsequent calls to ec2-describe-conversion-tasks.

Type: String

Default: None

Constraint: Maximum length of 255 characters

Required: No

Example: -d Test of ec2-import-instance

--user-data user_data

User data to be made available to the imported instance.

Type: String

Default: None

Required: No

Example: --user-data This is user data

--user-data-file disk_image_filename

The file containing user data made available to the imported instance.

Type: String

Default: None

Required: No

Example: --user-data-file my_data_file

--subnet subnet_id

[EC2-VPC] The ID of the subnet into which you're launching the instance.

Type: String

Default: None

Required: No

Example: --subnet subnet-f3e6ab83

--private-ip-address ip_address

[EC2-VPC] The specific IP address within subnet to use for the instance.

Type: String

Default: None

Required: No

Example: --private-ip-address 10.0.0.3

--monitor

Enables monitoring of the specified instances.

Type: String

Default: None

Required: No

Example: --monitor

--instance-initiated-shutdown-behavior behavior

Indicates whether an instance stops or terminates when you initiate shutdown from the instance (using the operating system command for system shutdown).

Type: String

Valid values: stop | terminate

Default: None

Required: No

Example: --instance-initiated-shutdown-behavior stop

-x, --expires days

The validity period for the signed Amazon S3 URLs that allow Amazon EC2 to access the manifest.

Type: String

Default: 30 days

Required: No

Example: -x 10

--ignore-region-affinity

Ignores the verification check to determine whether the bucket's region matches the region where the conversion task is created.

Type: None

Default: None

Required: No

Example: --ignore-region-affinity

--dry-run

Validates that the disk image matches a known type, without creating an import task.

Type: None

Default: None

Required: No

Example: --dry-run

--dont-verify-format

Skips verifying the file format. We don't recommend this option because it can result in a failed conversion.

Type: None

Default: None

Required: No

Example: --dont-verify-format

--no-upload

Creates an import task, without uploading a disk image to Amazon S3. To complete the import task and upload the disk image, use ec2-resume-import.

Type: None

Default: None

Required: No

Example: --no-upload

Common Options

OptionDescription

--region region

The region. Overrides the default region, the region specified by the EC2_URL environment variable, and the URL specified by the -U option.

Default: The region specified by the EC2_URL environment variable, or us-east-1 if EC2_URL isn't set.

-U, --url url

The uniform resource locator (URL) of the Amazon EC2 web service entry point.

Default: The endpoint specified by the EC2_URL environment variable, or https://ec2.amazonaws.com if EC2_URL isn't set.

-O, --aws-access-key aws_access_key_id

Your access key ID. For more information, see Tell the Tools Who You Are.

Default: The value of the AWS_ACCESS_KEY environment variable. If AWS_ACCESS_KEY isn't set, you must specify this option.

Example: -O AKIAIOSFODNN7EXAMPLE

-W, --aws-secret-key aws_secret_access_key

Your secret access key.

Default: The value of the AWS_SECRET_KEY environment variable. If AWS_SECRET_KEY isn't set, you must specify this option.

Example: -W wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

-T, --security-token delegation_token

The delegation token to pass along to the AWS request. This is only required when you are using temporary security credentials. For more information, see Using Temporary Security Credentials.

Default: The value of the AWS_DELEGATION_TOKEN environment variable (if set).

Example: -T AQoDYXdzEJr...<remainder of security token>

--connection-timeout timeout

The connection timeout, in seconds.

Example: --connection-timeout 30

--request-timeout timeout

The request timeout, in seconds.

Example: --request-timeout 45

-H, --headers

Includes column headers in the command output.

--show-empty-fields

Shows empty columns as (nil).

--hide-tags

Omits tags for tagged resources.

--debug

Displays internal debugging information. This can assist us when helping you troubleshooting problems.

-D, --auth-dry-run

Checks whether you have the required permissions for the command, without actually running the command. If you have the required permissions, the command returns DryRunOperation; otherwise, it returns UnauthorizedOperation.

-v, --verbose

Displays verbose output, including the API request and response on the command line. This is useful if you are building tools to talk directly to the Query API.

-

Reads arguments from standard input. This is useful when piping the output from one command to the input of another.

Example: ec2-describe-instances | grep stopped | cut -f 2 | ec2-start-instances -

-?, --help, -h

Displays usage information for the command.

Deprecated Options

We have deprecated the SOAP API for Amazon EC2. For more information, see SOAP Requests. From version 1.6.14.0 onwards of the Amazon EC2 CLI tools, the private key (-K, --private-key) and X.509 certificate (-C, --cert) options are not supported. Use your access key ID (-O, --aws-access-key) and secret access key (-W, --aws-secret-key) instead. For more information, see Setting Up the Amazon EC2 CLI and AMI Tools.

OptionDescription

-K, --private-key ec2_private_key

The private key to use when constructing requests to Amazon EC2.

Default: The value of the EC2_PRIVATE_KEY environment variable.

Example: -K pk-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem

-C, --cert ec2_cert

The X.509 certificate to use when constructing requests to Amazon EC2.

Default: The value of the EC2_CERT environment variable.

Example: -C cert-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem

Output

This command returns the following information:

  • Task ID, which you will use in other commands

  • General information about the disk image, such as the size and format

  • General information about the import operation, such as the status, bytes received, and expiration deadline

Amazon EC2 command line tools display errors on stderr.

Example

Example

This example command creates an import instance task that migrates a Windows Server 2008 SP2 (32-bit) VM into the us-east-1 region.

PROMPT> ec2-import-instance -t m1.xlarge ./WinSvr8-disk1.vmdk -f VMDK -o AKIAIOSFODNN7EXAMPLE -w wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY -b myawsbucket

Related Topics

Setting Up

IAM Policies

You can create an IAM policy to grant users permission to use this command. For more information, see IAM Policies for Amazon EC2 in the Amazon EC2 User Guide for Linux Instances.

Related Action