AWS Tools for Windows PowerShell
Command Reference

AWS services or capabilities described in AWS Documentation may vary by region/location. Click Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

Synopsis

Uploads a virtual machine image file to Amazon S3 and optionally requests import conversion to an Amazon EC2 instance.

Syntax

UploadAndImport (Default)

Import-EC2Instance
-ImageFile <String>
-FileFormat <String>
-BucketName <String>
-KeyPrefix <String>
-Description <String>
-VolumeSize <Int32>
-UploadThreadCount <Int32>
-Architecture <ArchitectureValues>
-AvailabilityZone <String>
-Group <String[]>
-InstanceInitiatedShutdownBehavior <String>
-InstanceType <InstanceType>
-Monitor <SwitchParameter>
-Platform <String>
-PrivateIpAddress <String>
-SubnetId <String>
-AdditionalInfo <String>
-Resume <SwitchParameter>
-RollbackOnUploadError <SwitchParameter>
-UrlExpiration <Int32>

UploadOnly

Import-EC2Instance
-ImageFile <String>
-UploadOnly <SwitchParameter>
-FileFormat <String>
-BucketName <String>
-KeyPrefix <String>
-Description <String>
-VolumeSize <Int32>
-UploadThreadCount <Int32>
-Resume <SwitchParameter>
-RollbackOnUploadError <SwitchParameter>
-UrlExpiration <Int32>

ImportFromManifest

Import-EC2Instance
-BucketName <String>
-ManifestFileKey <String[]>
-Architecture <ArchitectureValues>
-AvailabilityZone <String>
-Group <String[]>
-InstanceInitiatedShutdownBehavior <String>
-InstanceType <InstanceType>
-Monitor <SwitchParameter>
-Platform <String>
-PrivateIpAddress <String>
-SubnetId <String>
-AdditionalInfo <String>

Description

NOTE: This cmdlet has been deprecated and will be removed in a future release. Importing virtual machines and disk images to Amazon EC2 is now supported with the following cmdlets:
  • Import-EC2Image
  • Import-EC2Snapshot
  • Get-EC2ImportImageTask
  • Get-EC2ImportSnapshotTask
  • Stop-EC2ImportTask

Uploads and converts a virtual machine image into a new Amazon EC2 instance or uploads the virtual image artifacts and generated import manifest, pending a request to begin import conversion at a later time. With its default settings the cmdlet uploads the virtual machine image file to Amazon S3 as a series of individual S3 objects and creates a manifest to control the subsequent image conversion yielding an EC2 instance. Once upload of the artifacts is complete the cmdlet sends a request to EC2 to begin the image conversion. This mode yields a ConversionTask object that can be used to monitor conversion progress using the Get-EC2ConversionTask cmdlet or stop the in-flight conversion with Stop-EC2ConversionTask. If run with the -UploadOnly switch the cmdlet creates the import manifest for the machine image and uploads it together with the series of parts representing the virtual machine image file into Amazon S3, but does not initiate the conversion. In this mode the S3 object key of the uploaded manifest is output. Import conversion of the artifacts to an EC2 instance can be started at a later time by re-executing the cmdlet with the -ManifestFileKey parameter and the name of the bucket holding the artifacts. Note that if the upload of the image file fails, any successfully upload content together with the import manifest is retained by default in the specified bucket. This enables the cmdlet to be re-executed in 'resume' mode with the -Resume parameter to continue upload of the image file. If this behavior is not desired and content uploaded to the bucket before the failure occurred should be deleted, use the -RollbackOnUploadFailure switch. For more information about importing machine images and disk volumes into Amazon EC2, see Importing and Exporting Instances in the Amazon EC2 User Guide.

Parameters

-AdditionalInfo <String>
Reserved for internal use.
Required?False
Position?Named
Accept pipeline input?False
-Architecture <ArchitectureValues>
The architecture of the image. Using this option ensures that your image is imported as the expected instance type. Constraints:Allowed Values i386, x86_64
Required?True
Position?Named
Accept pipeline input?False
-AvailabilityZone <String>
The Availability Zone to launch the instance into.
Required?False
Position?Named
Accept pipeline input?False
-BucketName <String>
The name of the Amazon S3 bucket that will, or does, contain the manifest and image file artifacts. If the bucket does not exist an attempt will be made to create it before the artifacts are uploaded.For bucket creation to succeed, the bucket name must not already exist (bucket names are global).
Required?True
Position?Named
Accept pipeline input?False
-Description <String>
An optional comment describing the image. This comment is returned with the associated conversion task during enumeration with the Get-EC2ConversionTask cmdlet.
Required?False
Position?Named
Accept pipeline input?False
-FileFormat <String>
The file format of the disk image. If a value is not specified the cmdlet will attempt to infer it from the extension of the image file.Valid values: VMDK, RAW, VHD.
Required?False
Position?Named
Accept pipeline input?False
-Group <String[]>
The security group within which the instances should be run. Determines the ingress firewall rules that are applied to the launched instances.
Required?False
Position?Named
Accept pipeline input?False
-ImageFile <String>
Filename of the virtual machine disk image file to uploaded to Amazon S3 and imported into Amazon EC2. The cmdlet will perform the upload, manifest creation and presigned url generation and subsequent launch of the import conversion task returning a ConversionTask instance for progress monitoring to the pipeline.
Required?True
Position?1
Accept pipeline input?False
-InstanceInitiatedShutdownBehavior <String>
Indicates whether an instance stops or terminates when you initiate shutdown from the within the instance (using the operating system command for system shutdown). Constraints:Allowed Values stop, terminate
Required?False
Position?Named
Accept pipeline input?False
-InstanceType <InstanceType>
The type of instance to be launched. For more information, see Instance Types in the Amazon Elastic Compute Cloud User Guide. For more information about the Linux instance types you can import, see Before You Get Started in the Amazon Elastic Compute Cloud User Guide.
Required?True
Position?Named
Accept pipeline input?False
-KeyPrefix <String>
Optional prefix for the manifest and image file objects within the Amazon S3 bucket. The manifest and image file artifacts will be uploaded using keys consisting of this prefix and a generated GUID.
Required?False
Position?Named
Accept pipeline input?False
-ManifestFileKey <String[]>
If specified, the import process will be be started using a collection of manifests and image file artifacts that have been successfully uploaded previously to Amazon S3 (using the -UploadOnly switch). The collection of ConversionTask objects resulting from the operation are emitted to the pipeline.The parameter value is a collection of S3 object keys to existing manifest files. These keys are output when the cmdlet is run specifying the -UploadOnly switch or if an error occurrs when requesting import conversion be started (this allows you to re-start a conversion that failed due to a parameter error without uploading the image file(s) again.
Required?True
Position?Named
Accept pipeline input?False
-Monitor <SwitchParameter>
Enables monitoring of the specified instances.
Required?False
Position?Named
Accept pipeline input?False
-Platform <String>
The operating system of the instance. Default: Windows.Constraints:Allowed Values Windows, Linux
Required?False
Position?Named
Accept pipeline input?False
-PrivateIpAddress <String>
[EC2-VPC] The specific IP address within subnet to use for the instance.
Required?False
Position?Named
Accept pipeline input?False
-Resume <SwitchParameter>
If set, resumes a previous upload that was abandoned due to failure to upload one or more parts of the image file. Resuming an import applies only to the upload of the image artifacts. If Amazon EC2 returns an error from the resulting conversion you must start a new upload request to correct the issue.Note that if the cmdlet is run with the -RollbackOnUploadError switch set, resumption of the upload is not possible since the bucket contents will have been rolled back to delete the partially uploaded artifacts.
Required?False
Position?Named
Accept pipeline input?False
-RollbackOnUploadError <SwitchParameter>
If set and the image file fails to upload, the successfully uploaded parts and the manifest are removed automatically from S3 to avoid storage charges for potentially orphaned objects. By default the uploaded content is retained after error so that the cmdlet can be re-executed with the Resume parameter to resume upload of the failed content.
Required?False
Position?Named
Accept pipeline input?False
-SubnetId <String>
[EC2-VPC] The ID of the subnet into which you're launching the instance.
Required?False
Position?Named
Accept pipeline input?False
-UploadOnly <SwitchParameter>
If set the cmdlet constructs the import manifest and uploads it plus the image file artifacts to Amazon S3 but does not request import conversion be started. The S3 key of the uploaded manifest file is output to the pipeline. This key can be used subsequently as the value for the -ManifestFileKey parameter.
Required?True
Position?Named
Accept pipeline input?False
-UploadThreadCount <Int32>
Specifies the maximum number of threads to use to upload the image file parts to Amazon S3. Each thread will consume a minimum of 10MB of memory to handle the part data. Default: 10. Maximum: 30.
Required?False
Position?Named
Accept pipeline input?False
-UrlExpiration <Int32>
The validity period (in days) for the signed Amazon S3 URLs that allow Amazon EC2 to access the manifest. Default: 30 days. Note that for AWS regions requiring Signature Version 4 request signing, the maximum period is 7 days. Parameter values exceeding 7 are ignored for these regions.
Required?False
Position?Named
Accept pipeline input?False
-VolumeSize <Int32>
The size of the Amazon EBS volume, in GiB (2^30 bytes), that will hold the converted image. If not specified it will be calculated from the size of the image file, rounded up to the nearest GiB.Note: images intended for use as Amazon EC2 boot volumes must be a minimum of 8GiB in size.
Required?False
Position?Named
Accept pipeline input?False

Common Credential and Region Parameters

-AccessKey <String>
The AWS access key for the user account. This can be a temporary access key if the corresponding session token is supplied to the -SessionToken parameter.
Required? False
Position? Named
Accept pipeline input? False
-Credential <AWSCredentials>
An AWSCredentials object instance containing access and secret key information, and optionally a token for session-based credentials.
Required? False
Position? Named
Accept pipeline input? False
-ProfileLocation <String>

Used to specify the name and location of the ini-format credential file (shared with the AWS CLI and other AWS SDKs)

If this optional parameter is omitted this cmdlet will search the encrypted credential file used by the AWS SDK for .NET and AWS Toolkit for Visual Studio first. If the profile is not found then the cmdlet will search in the ini-format credential file at the default location: (user's home directory)\.aws\credentials. Note that the encrypted credential file is not supported on all platforms. It will be skipped when searching for profiles on Windows Nano Server, Mac, and Linux platforms.

If this parameter is specified then this cmdlet will only search the ini-format credential file at the location given.

As the current folder can vary in a shell or during script execution it is advised that you use specify a fully qualified path instead of a relative path.

Required? False
Position? Named
Accept pipeline input? False
-ProfileName <String>
The user-defined name of an AWS credentials or SAML-based role profile containing credential information. The profile is expected to be found in the secure credential file shared with the AWS SDK for .NET and AWS Toolkit for Visual Studio. You can also specify the name of a profile stored in the .ini-format credential file used with the AWS CLI and other AWS SDKs.
Required? False
Position? Named
Accept pipeline input? False
-NetworkCredential <PSCredential>
Used with SAML-based authentication when ProfileName references a SAML role profile. Contains the network credentials to be supplied during authentication with the configured identity provider's endpoint. This parameter is not required if the user's default network identity can or should be used during authentication.
Required? False
Position? Named
Accept pipeline input? False
-SecretKey <String>
The AWS secret key for the user account. This can be a temporary secret key if the corresponding session token is supplied to the -SessionToken parameter.
Required? False
Position? Named
Accept pipeline input? False
-SessionToken <String>
The session token if the access and secret keys are temporary session-based credentials.
Required? False
Position? Named
Accept pipeline input? False
-Region <String>
The system name of the AWS region in which the operation should be invoked. For example, us-east-1, eu-west-1 etc.
Required? False
Position? Named
Accept pipeline input? False
-EndpointUrl <String>

The endpoint to make the call against.

Note: This parameter is primarily for internal AWS use and is not required/should not be specified for normal usage. The cmdlets normally determine which endpoint to call based on the region specified to the -Region parameter or set as default in the shell (via Set-DefaultAWSRegion). Only specify this parameter if you must direct the call to a specific custom endpoint.

Required? False
Position? Named
Accept pipeline input? False

Inputs

This cmdlet does not accept pipeline input.

Outputs

This object contains the conversion task id of the import, assigned by Amazon EC2. This can be used to monitor the conversion or subsequently cancel it using Cancel-EC2ConversionTask. The service call response (type Amazon.EC2.Model.ImportInstanceResponse) can also be referenced from properties attached to the cmdlet entry in the $AWSHistory stack (if only one manifest or image was imported).
Contains the Amazon S3 object key of the import manifest file that was created and uploaded by the cmdlet. This value is returned when the cmdlet is executed with the -UploadOnly switch. Use this value with the -ManifestFileKey parameter to request conversion to an Amazon EC2 instance at a later time.

Examples

Example 1

PS C:\> Import-EC2Instance -ImageFile .\windows2012r2-disk1.vmdk -InstanceType m1.large -Architecture x86_64 -VolumeSize 30 `
-BucketName myimages -KeyPrefix windows2012r2.image -Platform Windows

ConversionTaskId : import-i-123456
ExpirationTime : 2014-06-23T15:45:03Z
ImportInstance : Amazon.EC2.Model.ImportInstanceTaskDetails
ImportVolume :
State : active
StatusMessage : Pending
Tags : {}
This example uploads and requests conversion of the specified disk image to a m1.large instance type with a volume size of 30GB. The file format parameter value is inferred from the file extension of the image file (vmdk). The image file artifacts are uploaded to the Amazon S3 bucket 'myimages' (created if it does not exist), with a key format of of '/windows2012r2.image/{guid}/windows2012r2-disk1.*, where {guid} is replaced by a new GUID formatted as 32 digits separated by hyphens. The conversion task object returned by Amazon EC2 is output to the pipeline and can be used to monitor conversion progress using Get-EC2ConversionTask or cancel it using Stop-EC2ConversionTask. If the image file upload fails, the manifest and any successfully uploaded image file content are retained in the S3 bucket so that the cmdlet can be re-executed in 'resume' mode to complete the import.

Example 2

PS C:\> Import-EC2Instance -ImageFile .\windows2012r2-disk1.vmdk -InstanceType m1.large -Architecture x86_64 -VolumeSize 30 `
-BucketName myimages -KeyPrefix windows2012r2.image -Platform Windows `
-RollbackOnUploadError

ConversionTaskId : import-i-123456
ExpirationTime : 2014-06-23T15:45:03Z
ImportInstance : Amazon.EC2.Model.ImportInstanceTaskDetails
ImportVolume :
State : active
StatusMessage : Pending
Tags : {}
This example uploads and requests conversion of the specified disk image. If the image file upload fails, the manifest and any successfully uploaded image file content are deleted from the S3 bucket because the -RollbackOnUploadError parameter is used.

Example 3

PS C:\> Import-EC2Instance -ImageFile .\windows2012r2-disk1.vmdk -InstanceType m1.large -Architecture x86_64 -VolumeSize 30 `
-BucketName myimages -KeyPrefix windows2012r2.image -Platform Windows `
-Resume

ConversionTaskId : import-i-123456
ExpirationTime : 2014-06-23T15:45:03Z
ImportInstance : Amazon.EC2.Model.ImportInstanceTaskDetails
ImportVolume :
State : active
StatusMessage : Pending
Tags : {}
This example resumes importing an instance after a previous upload failure. The cmdlet analyzes the import manifest for the image to determine which image file parts were not uploaded, and then uploads just those pieces. Note that 'resume' mode is not applicable if the -RollbackOnUploadError switch was used in the original upload command.

Example 4

PS C:\> Import-EC2Instance -ImageFile .\windows2012r2-disk1.vmdk -UploadOnly -VolumeSize 30 -BucketName myimages `
-KeyPrefix windows2012r2.image

windows2012r2.image/cc164294-94b0-42cc-ac8f-9ae2ddffaa53/windows2012r2-disk1.vmdkmanifest.xml
This example uploads an image file ready for conversion at a later time. The cmdlet outputs the S3 object key of the uploaded manifest. This can be used at a later time to start conversion using the -ManifestFileKey parameter. If the image file upload fails, the manifest and any successfully uploaded image file content are retained in the S3 bucket. Upload can then be resumed using the -Resume parameter as shown in other examples. Use the -RollbackOnUploadError switch to automatically clean the S3 bucket of any uploaded content after an error occurs during upload.

Example 5

PS C:\> Import-EC2Instance -ManifestFileKey "windows2012r2.image/cc164294-94b0-42cc-ac8f-9ae2ddffaa53/windows2012r2-disk1.vmdkmanifest.xml" `
-BucketName myimages -InstanceType m1.large -Architecture x86_64 -Platform Windows

ConversionTaskId : import-i-123456
ExpirationTime : 2014-06-23T15:45:03Z
ImportInstance : Amazon.EC2.Model.ImportInstanceTaskDetails
ImportVolume :
State : active
StatusMessage : Pending
Tags : {}
This example requests image file conversion using artifacts uploaded previously using the -UploadOnly parameter. The conversion task object returned by Amazon EC2 is output to the pipeline and can be used to monitor conversion progress using Get-EC2ConversionTask or cancel it using Stop-EC2ConversionTask. (Note that this variation of the parameters, replacing the -ImageFile parameter with the -ManifestFileKey parameter, is also used if an error occurs when requesting import conversion after successful upload of the image file and manifest. The error message in that scenario describes the parameter substitutions required to allow import to be resumed.)

Example 6

PS C:\> $m1 = Import-EC2Instance -ImageFile .\windows2012r2.vmdk -UploadOnly -BucketName myimages -KeyPrefix windows2012r2.image
PS C:\> $m2 = Import-EC2Instance -ImageFile .\windows2008r2.vmdk -UploadOnly -BucketName myimages -KeyPrefix windows2008r2.image

PS C:\> Import-EC2Instance -ManifestFileKey @($m1, $m2) -BucketName myimages -InstanceType m1.large -Architecture x86_64 -Platform Windows

ConversionTaskId : import-i-121212
ExpirationTime : 2014-06-23T15:45:03Z
ImportInstance : Amazon.EC2.Model.ImportInstanceTaskDetails
ImportVolume :
State : active
StatusMessage : Pending
Tags : {}

ConversionTaskId : import-i-232323
ExpirationTime : 2014-06-23T15:45:10Z
ImportInstance : Amazon.EC2.Model.ImportInstanceTaskDetails
ImportVolume :
State : active
StatusMessage : Pending
Tags : {}
This example requests image file conversion for a collection of images uploaded previously using the -UploadOnly switch. The conversion task object for each image is output to the pipeline and can be used to monitor conversion progress using Get-EC2ConversionTask or cancel it using Stop-EC2ConversionTask. In this example, the volume size for the imported instance is inferred from the size of the image file.

Supported Version

AWS Tools for PowerShell: 2.x.y.z