Synopsis
Uploads a virtual disk image file to Amazon S3 and optionally requests import conversion to an EBS volume.
Syntax
UploadAndImport (Default)
Import-EC2Volume-ImageFile <String>-FileFormat <String>-BucketName <String>-KeyPrefix <String>-Description <String>-VolumeSize <Int32>-UploadThreadCount <Int32>-AvailabilityZone <String>-Resume <SwitchParameter>-RollbackOnUploadError <SwitchParameter>-UrlExpiration <Int32>UploadOnly
Import-EC2Volume-ImageFile <String>-UploadOnly <SwitchParameter>-FileFormat <String>-BucketName <String>-KeyPrefix <String>-Description <String>-VolumeSize <Int32>-UploadThreadCount <Int32>-Resume <SwitchParameter>-RollbackOnUploadError <SwitchParameter>-UrlExpiration <Int32>ImportFromManifest
Import-EC2Volume-BucketName <String>-ManifestFileKey <String[]>-AvailabilityZone <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:
Uploads and converts a virtual machine disk image, creating a new Amazon Elastic Block Store (EBS) volume or uploads the disk 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 disk image file to Amazon S3 as a series of individual Amazon S3 objects and creates a manifest to control the subsequent image conversion yielding an EBS volume. Once upload of the artifacts is complete the cmdlet sends a request to EC2 to begin the volume 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 disk image and uploads it together with the series of parts representing the disk 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 EBS volume 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.
- Import-EC2Image
- Import-EC2Snapshot
- Get-EC2ImportImageTask
- Get-EC2ImportSnapshotTask
- Stop-EC2ImportTask
Uploads and converts a virtual machine disk image, creating a new Amazon Elastic Block Store (EBS) volume or uploads the disk 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 disk image file to Amazon S3 as a series of individual Amazon S3 objects and creates a manifest to control the subsequent image conversion yielding an EBS volume. Once upload of the artifacts is complete the cmdlet sends a request to EC2 to begin the volume 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 disk image and uploads it together with the series of parts representing the disk 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 EBS volume 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
-AvailabilityZone <String>
The Availability Zone for the resulting Amazon EBS volume.
| Required? | True |
| 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 |
-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 |
-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 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 |
-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 |
-UploadOnly <SwitchParameter>
If set the cmdlet constructs the import manifest and uploads it plus the image file to Amazon S3 but does not request import conversion be started. The S3 key of the uploaded manifest file is output. 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.ImportVolumeResponse) 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 EBS volume at a later time.
Examples
Example 1
PS C:\> Import-EC2Volume -ImageFile .\mydiskvolume.vmdk -VolumeSize 4 -BucketName myimages -Region us-west-2 -AvailabilityZone us-west-2a
ConversionTaskId : import-vol-123456
ExpirationTime : 2014-06-23T15:45:03Z
ImportInstance : Amazon.EC2.Model.ImportVolumeTaskDetails
ImportVolume :
State : active
StatusMessage : Pending
Tags : {}This example uploads and requests conversion of the specified disk image to an Amazon EBS volume of size 4 GB. 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 '/{guid}/mydiskvolume.*, where {guid} will be 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.
Example 2
PS C:\> Import-EC2Volume -ImageFile .\diskvolume1.vmdk -UploadOnly -BucketName myimages -KeyPrefix mydiskvolumes
mydiskvolumes/cc164294-94b0-42cc-ac8f-9ae2ddffaa53/diskvolume1.vmdkmanifest.xmlThis example uploads the artifacts for the specified disk image to Amazon S3. The volume size of the eventual Amazon EBS volume (when converted) is set to the larger of 8 GB or the image file size. The file format 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 '/mydiskvolumes/{guid}/diskvolume1.*, where {guid} is replaced by a new GUID formatted as 32 digits separated by hyphens. 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.
Example 3
PS C:\> Import-EC2Volume -ManifestFileKey "mydiskvolumes/cc164294-94b0-42cc-ac8f-9ae2ddffaa53/diskvolume1.vmdkmanifest.xml" `
-BucketName myimages -Region us-west-2 -AvailabilityZone us-west-2a
ConversionTaskId : import-vol-654321
ExpirationTime : 2014-06-23T15:45:03Z
ImportInstance : Amazon.EC2.Model.ImportVolumeTaskDetails
ImportVolume :
State : active
StatusMessage : Pending
Tags : {}This example requests image file conversion using artifacts uploaded previously using the -UploadOnly switch. 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.
Example 4
PS C:\> $m1 = Import-EC2Volume -ImageFile .\diskvolume1.vmdk -UploadOnly -BucketName myimages -KeyPrefix mydiskvolumes
PS C:\> $m2 = Import-EC2Volume -ImageFile .\diskvolume2.vmdk -UploadOnly -BucketName myimages -KeyPrefix mydiskvolumes
PS C:\> $m3 = Import-EC2Volume -ImageFile .\diskvolume3.vmdk -UploadOnly -BucketName myimages -KeyPrefix mydiskvolumes
PS C:\> Import-EC2Volume -ManifestFileKey @($m1, $m2, $m3) ` -BucketName myimages -Region us-west-2 -AvailabilityZone us-west-2a
ConversionTaskId : import-vol-212121
ExpirationTime : 2014-06-23T15:45:03Z
ImportInstance : Amazon.EC2.Model.ImportVolumeTaskDetails
ImportVolume :
State : active
StatusMessage : Pending
Tags : {}
ConversionTaskId : import-vol-323232
ExpirationTime : 2014-06-23T15:45:10Z
ImportInstance : Amazon.EC2.Model.ImportVolumeTaskDetails
ImportVolume :
State : active
StatusMessage : Pending
Tags : {}
ConversionTaskId : import-vol-434343
ExpirationTime : 2014-06-23T15:45:15Z
ImportInstance : Amazon.EC2.Model.ImportVolumeTaskDetails
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.
Example 5
PS C:\> Import-EC2Volume -ImageFile .\mydiskvolume.vmdk -VolumeSize 4 -BucketName myimages -Region us-west-2 -AvailabilityZone us-west-2a `
-RollbackOnUploadErrorThis example runs the cmdlet so that if an upload error occurs, any content uploaded prior to the error is automatically deleted from the S3 bucket. Note that when the -RollbackOnUploadError parameter is used, it is not possible to re-run the cmdlet in 'resume' mode.
Example 6
PS C:\> Import-EC2Volume -ImageFile .\mydiskvolume.vmdk -VolumeSize 4 -BucketName myimages -Region us-west-2 -AvailabilityZone us-west-2a `
-ResumeThis example resumes importing a volume 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.
Related Links
Supported Version
AWS Tools for PowerShell: 2.x.y.z
