image management 3.4 spec imaging toolkit

Table of Contents Image Toolkit API Ansible Mounters Image Validators Converters Runtime Validators Crypt Bundlers References

Image Toolkit API

A collection of utilities in several classes (detailed below) that, when composed in a process, handle the micro-steps of various image management processes. The classes are Mounters, Validators, Converters, and Runtime Validators.

Collection of utilities which are composed to define the various image management processes.
Extensible: each of the below classes has to be extensible so that a particular mounter,
Partial execution
State feedback
Sub-task resource management
The parts of image toolkit are in the following table

Name	Description
Mounters	Are able to mount a particular type of image.
Image Validators	Scripts which are executed against a mounted image, under certain conditions, and tests one assertion that must be true.
Converters	These change an input disk image from one type to another.
Instance Validators	Scripts which execute within a running instance and perform sanity checks before an imported instance is returned to the user.
Crypt	This is the mechanism used for encrypting and decrypting images.
Bundlers	This is the mechanism used for bundling/unbundling images which are stored in the object store.

Ansible

A quick investigation indicates that it may be possible to express the orchestration of the image toolkit operations as an ansible playbook. That is, it has the following attributes:

Small and sensible set of dependencies (yaml and jinja2)
Support for nested playbooks: this is necessary so that the service implementation may execute the leaves of the validation/conversion/runtime-validation/crypt stages piecemeal.
Support for operating on a chroot'd image ^[1] (verified present in the 1.2 release; which is current)
Supports instrumentation of playbook execution to through callbacks to allow externalizing execution state ^[2]

Mounters

These which are able to mount a particular disk image type.

Raw disk: this is the most important one.
Disk partition: this is the ami/ari/aki case.
VMDK: this is the AWS defined instance import case.
Others: any others are out of scope.

Function	Arguments	Return Value	Notes
accepts	diskType	boolean	Checks if this mounter is able to mount the argument disk type
	diskType	String	Describing the image type

mount	diskType, filePath, mountPoint	void	Mounts the disk image at filePath onto mountPoint using the mounter for diskType
	diskType	String	describing the image type
	filePath	String	the path to the disk image
	mountPoint	String	the path to the directory which serves as the mount point
	errors	exceptions	Occur when the tool fails (and the exception clarifies the reason) or when a failure occurs for any other reason (in which case at least the context of the failure is reported if no further information is available).

Image Validators

These are scripts which are executed against a mounted image, under certain conditions, and tests one assertion that must be true. A validator can be optional which means that its failure is recorded and reported but does not result in aborting the calling image management process.

Function	Arguments	Return Value	Notes
accepts	platform	boolean	Checks if this validator applies to the given platform and os pair
	platform	Enum	Describing the operating system, either linux, windows, unknown

validate	none	String	Performs a single test and fails with a descriptive exception when there is an error. Returns a String describing the check which was performed when it succeeds.
	errors	exceptions	Occur when the tool fails (and the exception clarifies the reason) or when a failure occurs for any other reason (in which case at least the context of the failure is reported if no further information is available).

optional	none	boolean	Returns true if the validator is optional. If it is optional, errors which occur when invoking validate are treated as warnings: They are recorded and reported to the user, but the image management process continues

Converters

These change an input disk image from one type to another. Conversion has several wrinkles which need to be kept in mind. It can be a multi step process and intermediate state information is needed to understand what is happening. It can be a long running process so progress information is similarly important. Last, conversion can demand a

Raw disk -> Raw disk: The trivial case.
AMI -> Raw disk: This has two parts: partition based and disk based images.
VMDK -> Raw disk: This is much like euca_imager

Note that converters are defined here in a manner that supports eventual implementation of round-trip conversion. That is, from VMDK to Raw disk and also back from Raw disk to VMDK.

Function	Arguments	Return Value	Notes
accepts	sourceImageType, destImageType	boolean	Checks if this converter applies to the given sourceType and destType
	sourceImageType	String	Describing the source image type
	destImageType	String	Describing the destination image type
	exceptions	TBD	Exceptions must only occur when the tool determines that it should be performing the but knows apriori that the resources required are not available (e.g., disk space). A failure of assumptions in the accepts method (e.g., missing dependencies) must never result in throwing an exception; it should return false.

requiredCapacity	sourceImageType, destImageType	long	Returns the additional capacity required to perform the operation
	sourceImageType	String	Describing the source image type
	destImageType	String	Describing the destination image type

convert	sourceImageType, destImageType, sourceFilePath, destFilePath	String	Performs the conversion of sourceFilePath stored in sourceImageType and converts it to destImageType in the file destFilePath. Returns a String describing the check which was performed when it succeeds.
	sourceImageType	String	Describing the source image type
	destImageType	String	Describing the destination image type
	sourceFilePath	String	Indicating the source image path
	destFilePath	String	Indicating the destination image path
	exceptions	TBD	Occur when the tool fails (and the exception clarifies the reason) or when a failure occurs for any other reason (in which case at least the context of the failure is reported if no further information is available).

Runtime Validators

These are scripts which execute within a running instance and perform sanity checks before an imported instance is returned to the user.

Function	Arguments	Return Value	Notes
accepts	platform	boolean	Checks if this validator applies to the given platform and os pair
	platform	Enum	Describing the operating system, either linux, windows, unknown

validate	none	String	Performs a single test and fails with a descriptive exception when there is an error. Returns a String describing the check which was performed when it succeeds. Note: it is not an error for a validator to be run against an unsupported flavor of the platform type: This case should be indicated by a human readable message stating the mismatch of expectations (e.g., "Expected RHEL/CentOS or 5.x/6.x, but failed to find /etc/redhat-version")
	exceptions	TBD	Occur when the tool fails (and the exception clarifies the reason) or when a failure occurs for any other reason (in which case at least the context of the failure is reported if no further information is available).

optional	none	boolean	Returns true if the validator is optional. If it is optional, errors which occur when invoking validate are treated as warnings: They are recorded and reported to the user, but the image management process continues

Crypt

This is the mechanism used for encrypting and decrypting images. Today the implementation is singular, but will be handled here as if multiplicity existed. This should be understood as meaning the same mechanism be used to orchestrate the encrypt/decrypt actions and they are not embedded in the service or image toolkit implementation. That is, their execution is expressed as part of the workflow.

Function	Arguments	Return Value	Notes
accepts	sourceCryptType, destCryptType	boolean	Checks if this encrypt/decrypt script applies to the given sourceCryptType and destCryptType encryption types. One of sourceCryptType and destCryptType is necessarily "none" -- that is, not encrypted.
	sourceCryptType	String	Describing the source encryption type; possible "none"
	destCryptType	String	Describing the destination encryption type; possible "none"
	exceptions	TBD	Exceptions must only occur when the tool determines that it should be performing the but knows apriori that the resources required are not available (e.g., disk space). A failure of assumptions in the accepts method (e.g., missing dependencies) must never result in throwing an exception; it should return false.

crypt	sourceCryptType, destCryptType, sourceFilePath, destFilePath	String	Performs the conversion of sourceFilePath, encrypted as sourceCryptType, and de/encrypts it to destFilePath as appropriate for destCryptType
	sourceCryptType	String	Describing the source image encryption type
	destCryptType	String	Describing the destination image encryption type
	exceptions	TBD	Exceptions occur when the tool fails (and the exception clarifies the reason) or when a failure occurs for any other reason (in which case at least the context of the failure is reported if no further information is available).

Bundlers

This is the mechanism used for bundling and unbundling of images. Today the implementation is singular, but will be handled here as if multiplicity existed. This should be understood as meaning the same mechanism be used to orchestrate the bundling/unbundling actions and they are not embedded in the service or image toolkit implementation. That is, their execution is expressed as part of the workflow.

Function	Arguments	Return Value	Notes
accepts	sourceCryptType, destCryptType	boolean	Checks if this encrypt/decrypt script applies to the given sourceCryptType and destCryptType encryption types. One of sourceCryptType and destCryptType is necessarily "none" -- that is, not encrypted.
	sourceCryptType	String	Describing the source encryption type; possible "none"
	destCryptType	String	Describing the destination encryption type; possible "none"
	exceptions	TBD	Exceptions must only occur when the tool determines that it should be performing the but knows apriori that the resources required are not available (e.g., disk space). A failure of assumptions in the accepts method (e.g., missing dependencies) must never result in throwing an exception; it should return false.

crypt	sourceCryptType, destCryptType, sourceFilePath, destFilePath	String	Performs the conversion of sourceFilePath, encrypted as sourceCryptType, and de/encrypts it to destFilePath as appropriate for destCryptType
	sourceCryptType	String	Describing the source image encryption type
	destCryptType	String	Describing the destination image encryption type
	exceptions	TBD	Exceptions occur when the tool fails (and the exception clarifies the reason) or when a failure occurs for any other reason (in which case at least the context of the failure is reported if no further information is available).