C# Class Amazon.EC2.Import.DiskImageImporter

Helper class to import a virtual machine image or disk image to Amazon EC2 using Amazon S3 to hold the in-flight artifacts.

Show file Open project: aws/aws-sdk-net Class Usage Examples

Private Properties

Property	Type	Description
ConstructImportPartsList	Import
ConstructManifestArtifactKey	void
CreateImportManifest	ImportManifestRoot
DeserializeManifestFromS3	void
DetermineRemainingUploads	void
GetPresignedManifestUrl	string
RemoveUploadedArtifacts	bool
UploadImageFilePart	void
UploadImageParts	void
UploadManifest	void
VolumeSizeFor	long

Public Methods

Method	Description
DiskImageImporter ( AWSCredentials credentials, RegionEndpoint region, string bucketName ) : System	Constructs an image importer to upload and convert virtual machine image or disk volumes for use with Amazon EC2.
DiskImageImporter ( ICoreAmazonS3 s3Client, IAmazonEC2 ec2Client, string bucketName ) : System	Constructs an image importer to upload and convert virtual machine image or disk volumes for use with Amazon EC2. The importer will use the supplied clients for communicating with Amazon S3 and Amazon EC2. Note that the clients should be configured to use the same region and AWS account.
DiskImageImporter ( RegionEndpoint region, string bucketName ) : System	Constructs an image importer to upload and convert virtual machine image or disk volumes for use with Amazon EC2. AWS credentials will be obtained from the application configuration settings.
FromManifest ( AWSCredentials credentials, RegionEndpoint region, string bucketName, string manifestFileKey, bool resumingUpload ) : DiskImageImporter	Constructs an importer instance for a previously uploaded manifest. The manifest is downloaded using a new Amazon S3 client constructed for the specified region and deserialized, ready for use in constructing the appropriate ImportInstance or ImportVolume request to Amazon EC2.
ImportInstance ( string imageFilepath, string fileFormat, long volumeSize, string keyPrefix, ImportLaunchConfiguration launchConfiguration, ImportProgressCallback progressCallback ) : ImportInstanceResponse	Uploads and requests import conversion of a virtual machine image file to an Amazon EC2 instance.
ImportVolume ( string imageFilepath, string fileFormat, long volumeSize, string keyPrefix, string availabilityZone, string description, ImportProgressCallback progressCallback ) : ImportVolumeResponse	Uploads and requests import conversion of a virtual disk file to an Amazon EBS volume.
PopulateDiskImage ( string manifestFileKey, string description ) : DiskImage	Helper to populate a DiskImage instance from the SDK that will be used in an ImportInstance API request using data previously recorded in the import manifest.
PopulateDiskImageDetail ( string manifestFileKey ) : DiskImageDetail	Helper to populate a DiskImageDetail instance from the SDK that will be used in an ImportVolume API request using data previously recorded in the import manifest.
PopulateLaunchSpecificationInstance ( ImportLaunchConfiguration config ) : ImportInstanceLaunchSpecification	Helper to populate an SDK ImportInstanceLaunchSpecification instance that will be used in an ImportInstance API request.
PopulateVolumeDetail ( ) : VolumeDetail	Helper to populate a VolumeDetail instance from the SDK that will be used in an ImportInstance or ImportVolume API request using data previously recorded in the import manifest.
StartInstanceConversion ( ImportLaunchConfiguration launchConfiguration ) : ImportInstanceResponse	Initiates a conversion task to yield a new Amazon EC2 instance for a set of image file artifacts uploaded previously to Amazon S3.
StartVolumeConversion ( string availabilityZone, string description ) : ImportVolumeResponse	Initiates a conversion task to yield a new EBS volume for a set of image file artifacts uploaded previously to Amazon S3.
Upload ( string imageFilepath ) : string	Constructs the import manifest for the image and then uploads it and the virtual machine image or disk image to Amazon S3. The S3 key to the uploaded manifest file is returned. If an error occurs during upload of the image file the RetainArtifactsOnUploadError property governs whether the partially uploaded content is deleted or retained. If the content is retained, the import can be resumed. By default the RetainArtifactsOnUploadError property is false and the content deleted, avoiding storage charges for potentially orphaned content if the command is not re-run.
Upload ( string imageFilepath, string fileFormat, long volumeSize, string keyPrefix, ImportProgressCallback progressCallback, bool resumeUpload ) : string	Constructs the import manifest for the image and then uploads it and the virtual machine image or disk image to Amazon S3. The S3 key to the uploaded manifest file is returned. If an error occurs during upload of the image file the RetainArtifactsOnUploadError property governs whether the partially uploaded content is deleted or retained. If the content is retained, the import can be resumed. By default the RetainArtifactsOnUploadError property is false and the content deleted, avoiding storage charges for potentially orphaned content if the command is not re-run.

Private Methods

Method	Description
ConstructImportPartsList ( long volumeSize, System.DateTime urlExpiration ) : Import	Walks the byte ranges of the image file to construct the logical parts we'll use to perform the upload
ConstructManifestArtifactKey ( string imageFilepath ) : void	Constructs the S3 object key for the manifest artifact. This will combine the root key, any optional prefix the user has requested be applied and the filename of the artifact, plus a fixed extension.
CreateImportManifest ( string fileFormat, long volumeSize ) : ImportManifestRoot	Constructs the object hierarchy that will be serialized to a single manifest file describing the import.
DeserializeManifestFromS3 ( ) : void	Downloads the manifest from Amazon S3 and deserializes the contents.
DetermineRemainingUploads ( ) : void	Analyzes the parts list of the manifest to determine which object parts exist in S3. Used when instantiating an importer from an existing manifest of a failed uploaded (RetainArtifactsOnUploadError set true to keep the partially uploaded content allowing uploads to be resumed part-way through). Since the manifest contains a set of presigned urls to each part we can make use of those to determine whether a part has been uploaded or not.
GetPresignedManifestUrl ( string manifestFileKey ) : string	Constructs the presigned url to the import manifest in S3.
RemoveUploadedArtifacts ( string manifestFileKey, IEnumerable partsList ) : bool	Removes the manifest and iterates through the parts list to see which parts had been completed when failures occur and removes those objects to avoid storage cost to the user (if the user retries the command, a different root key guid will be generated leading to potential orphans).
UploadImageFilePart ( object state ) : void	Threadpool delegate to process image file parts one by one and upload to Amazon S3. If an error occurs, we abandon the part and continue to seek new ones (even though we won't process them, only signal). This allows all threads to exit before we attempt error clean up.
UploadImageParts ( ImportProgressCallback progressCallback = null ) : void	Uploads the image file to S3 as a series of distinct 10MB objects, as required by EC2, using the constructed import manifest as a guide. If any part fails to upload, we clean up successfully uploaded parts before returning the error to the caller.
UploadManifest ( ImportProgressCallback progressCallback = null ) : void	Serialize and upload the constructed import manifest using the supplied S3 client with optional progress callback.
VolumeSizeFor ( long diskImageSize, long requestedSize ) : long	Computes the size of the volume to hold the image in EC2, with optional override by the user. Observation of the EC2 CLI shows a preferred minimum size for boot volumes of 8GB.

Method Details

DiskImageImporter() public method

Constructs an image importer to upload and convert virtual machine image or disk volumes for use with Amazon EC2.

public DiskImageImporter ( AWSCredentials credentials, RegionEndpoint region, string bucketName ) : System
credentials	Amazon.Runtime.AWSCredentials	/// The AWS credentials of the account that will own the uploaded artifacts. ///
region	RegionEndpoint	/// The region to which the artifacts will be uploaded and EC2 conversion performed. ///
bucketName	string	/// The name of the Amazon S3 bucket that will contain the uploaded image and manifest. If the bucket /// does not exist it will be created. ///
return	System

DiskImageImporter() public method

Constructs an image importer to upload and convert virtual machine image or disk volumes for use with Amazon EC2. The importer will use the supplied clients for communicating with Amazon S3 and Amazon EC2. Note that the clients should be configured to use the same region and AWS account.

public DiskImageImporter ( ICoreAmazonS3 s3Client, IAmazonEC2 ec2Client, string bucketName ) : System
s3Client	ICoreAmazonS3	Client to use to upload artifacts to Amazon S3
ec2Client	IAmazonEC2	Client to use to request image conversion in Amazon EC2
bucketName	string	/// The name of the Amazon S3 bucket that will contain the uploaded image and manifest. If the bucket /// does not exist it will be created. ///
return	System

DiskImageImporter() public method

Constructs an image importer to upload and convert virtual machine image or disk volumes for use with Amazon EC2. AWS credentials will be obtained from the application configuration settings.

public DiskImageImporter ( RegionEndpoint region, string bucketName ) : System
region	RegionEndpoint	/// The region to which the artifacts will be uploaded and EC2 conversion performed. ///
bucketName	string	/// The name of the Amazon S3 bucket that will contain the uploaded image and manifest. If the bucket /// does not exist it will be created. ///
return	System

FromManifest() public static method

Constructs an importer instance for a previously uploaded manifest. The manifest is downloaded using a new Amazon S3 client constructed for the specified region and deserialized, ready for use in constructing the appropriate ImportInstance or ImportVolume request to Amazon EC2.

public static FromManifest ( AWSCredentials credentials, RegionEndpoint region, string bucketName, string manifestFileKey, bool resumingUpload ) : DiskImageImporter
credentials	Amazon.Runtime.AWSCredentials	/// The AWS credentials for the account that owns or has access to the bucket containing the manifest file. ///
region	RegionEndpoint	The region in which the Amazon S3 client used for download will be constructed.
bucketName	string	The name of the bucket containing the manifest file.
manifestFileKey	string	The S3 object key of the manifest file.
resumingUpload	bool	/// Set this to true if a previous upload failed part-way through processing and RetainArtifactsOnUploadError /// was set to true so the partially uploaded content was retained. The existing manifest will /// be inspected and uploads can then resume to process the retaining content. ///
return	DiskImageImporter

ImportInstance() public method

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

public ImportInstance ( string imageFilepath, string fileFormat, long volumeSize, string keyPrefix, ImportLaunchConfiguration launchConfiguration, ImportProgressCallback progressCallback ) : ImportInstanceResponse
imageFilepath	string	The full path to the image file to be processed
fileFormat	string	/// The format of the image file (VMDK \| RAW \| VHD). If not specified, it will be inferred /// from the extension of the image file. ///
volumeSize	long	/// The requested size (in GiB) for the resulting image volume. If not specified a suitable /// value based on the size of the image file is used. Note that the minimum required boot /// volume size for EC2 is 8GB. ///
keyPrefix	string	/// Optional root-level key prefix that will be applied to the uploaded artifacts in S3. /// The artifacts will be placed beneath this (or the root if not set) in a key composed /// of a GUID. ///
launchConfiguration	ImportLaunchConfiguration	Launch configuration settings for the imported instance
progressCallback	ImportProgressCallback	Optional callback delegate for upload progress reporting
return	Amazon.EC2.Model.ImportInstanceResponse

ImportVolume() public method

Uploads and requests import conversion of a virtual disk file to an Amazon EBS volume.

public ImportVolume ( string imageFilepath, string fileFormat, long volumeSize, string keyPrefix, string availabilityZone, string description, ImportProgressCallback progressCallback ) : ImportVolumeResponse
imageFilepath	string	The full path to the image file to be processed
fileFormat	string	/// The format of the image file (VMDK \| RAW \| VHD). If not specified, it will be inferred /// from the extension of the image file. ///
volumeSize	long	/// The requested size (in GiB) for the resulting image volume. If not specified a suitable /// value based on the size of the image file is used. ///
keyPrefix	string	/// Optional root-level key prefix that will be applied to the uploaded artifacts in S3. /// The artifacts will be placed beneath this (or the root if not set) in a key composed /// of a GUID. ///
availabilityZone	string	The Availability Zone for the resulting Amazon EBS volume.
description	string	An optional description for the volume being imported.
progressCallback	ImportProgressCallback	Optional callback delegate for upload progress reporting
return	Amazon.EC2.Model.ImportVolumeResponse

PopulateDiskImage() public method

Helper to populate a DiskImage instance from the SDK that will be used in an ImportInstance API request using data previously recorded in the import manifest.

public PopulateDiskImage ( string manifestFileKey, string description ) : DiskImage
manifestFileKey	string	The Amazon S3 object key of the manifest file.
description	string	Optional description for the image.
return	Amazon.EC2.Model.DiskImage

PopulateDiskImageDetail() public method

Helper to populate a DiskImageDetail instance from the SDK that will be used in an ImportVolume API request using data previously recorded in the import manifest.

public PopulateDiskImageDetail ( string manifestFileKey ) : DiskImageDetail
manifestFileKey	string	The Amazon S3 object key of the manifest file.
return	Amazon.EC2.Model.DiskImageDetail

PopulateLaunchSpecificationInstance() public static method

Helper to populate an SDK ImportInstanceLaunchSpecification instance that will be used in an ImportInstance API request.

public static PopulateLaunchSpecificationInstance ( ImportLaunchConfiguration config ) : ImportInstanceLaunchSpecification
config	ImportLaunchConfiguration	Settings for the new LaunchSpecificationInstance
return	Amazon.EC2.Model.ImportInstanceLaunchSpecification

PopulateVolumeDetail() public method

Helper to populate a VolumeDetail instance from the SDK that will be used in an ImportInstance or ImportVolume API request using data previously recorded in the import manifest.

public PopulateVolumeDetail ( ) : VolumeDetail
return	Amazon.EC2.Model.VolumeDetail

StartInstanceConversion() public method

Initiates a conversion task to yield a new Amazon EC2 instance for a set of image file artifacts uploaded previously to Amazon S3.

public StartInstanceConversion ( ImportLaunchConfiguration launchConfiguration ) : ImportInstanceResponse
launchConfiguration	ImportLaunchConfiguration	Launch configuration settings for the imported instance
return	Amazon.EC2.Model.ImportInstanceResponse

StartVolumeConversion() public method

Initiates a conversion task to yield a new EBS volume for a set of image file artifacts uploaded previously to Amazon S3.

public StartVolumeConversion ( string availabilityZone, string description ) : ImportVolumeResponse
availabilityZone	string	The Availability Zone for the resulting Amazon EBS volume.
description	string	An optional description for the volume being imported.
return	Amazon.EC2.Model.ImportVolumeResponse

Upload() public method

Constructs the import manifest for the image and then uploads it and the virtual machine image or disk image to Amazon S3. The S3 key to the uploaded manifest file is returned.

If an error occurs during upload of the image file the RetainArtifactsOnUploadError property governs whether the partially uploaded content is deleted or retained. If the content is retained, the import can be resumed. By default the RetainArtifactsOnUploadError property is false and the content deleted, avoiding storage charges for potentially orphaned content if the command is not re-run.

public Upload ( string imageFilepath ) : string
imageFilepath	string	The full path to the image file to be processed
return	string

Upload() public method

Constructs the import manifest for the image and then uploads it and the virtual machine image or disk image to Amazon S3. The S3 key to the uploaded manifest file is returned.

public Upload ( string imageFilepath, string fileFormat, long volumeSize, string keyPrefix, ImportProgressCallback progressCallback, bool resumeUpload ) : string
imageFilepath	string	The full path to the image file to be processed
fileFormat	string	/// The format of the image file (VMDK \| RAW \| VHD). If not specified, it will be inferred /// from the extension of the image file. ///
volumeSize	long	/// The requested size (in GiB) for the resulting image volume. If not specified a suitable /// value based on the size of the image file is used. Note that if importing a disk image that /// will be used as an EC2 instance, the minimum required boot volume size is 8GB. ///
keyPrefix	string	/// Optional root-level key prefix that will be applied to the uploaded artifacts in S3. /// The artifacts will be placed beneath this (or the root if not set) in a key composed /// of a GUID. ///
progressCallback	ImportProgressCallback	Optional callback delegate for upload progress reporting
resumeUpload	bool	/// Set this to true if a previous upload failed part-way through processing and RetainArtifactsOnUploadError /// was set to true so the partially uploaded content was retained. The existing manifest will /// be inspected and uploads will resume of the retaining content. ///
return	string