image2class Reference

image2class is only available in the AppLogic 2.9 production release and later versions.

Overview

The image2class utility imports virtual machine images as AppLogic appliance classes. This makes it easy for users to migrate workloads from existing virtualization deployments into AppLogic. The virtual machine image that is being imported may be located on either the grid's impex volume or on a remote site accessible over HTTP/HTTPS. The AppLogic appliance class that is created from the virtual machine can either be unmanaged or managed:

An unmanaged AppLogic appliance class does not contain any modifications to the imported volumes from the virtual machine image. In this case the appliance runs in the hardware virtualization mode (HVM).
A managed AppLogic appliance class is modified during the import process to use the AppLogic Appliance Kit (APK), which enhances the appliance with the following characteristics:
- allows the appliance to define its own boundary which consists of the following:
  - property settings which allow the customization of the appliance behavior and configuration
  - terminals which are used to communicate with other AppLogic appliances within the same application
  - default interface that is used to access the appliance within the grid shell (ssh)
- allows the appliance to log informational/error messages to the grid's message log and dashboard to communicate important information to the users
- ability to collect and analyze appliance resource and performance counters (CPU utilization, memory usage, etc)
- reports appliance life-cycle events to AppLogic for the purposes of life-cycle management (tracking when the appliance has booted, appliance debugging, etc)

image2class currently supports only virtual machines that comply with the Open Virtualization Format (OVF). For managed appliances, only redhat/debian based OVF images are currently supported. image2class will eventually be extended to support other image formats such as Virtual Hard Disk (VHD). image2class automatically detects the type of image by the file extension of the image.

The image2class utility supports only OVA-style packaging. When importing an OVA image, image2class uses the configuration provided in the .ovf descriptor to generate a class descriptor for the AppLogic appliance (either a singleton or a catalog class). Since the .ovf descriptor does not provide all of the information needed to properly create an AppLogic appliance class, image2class provides command line options for specifying/overriding the class configuration (default values are also used where appropriate). If the OVF image contains an AppLogic appliance class descriptor in ADL format, the utility uses this descriptor for the AppLogic appliance.

Usage

image2class is invoked from the AppLogic command line shell using util image2class. Help is displayed using help util image2class.

Syntax: util image2class <class> <image> <--managed|--unmanaged|--upgrade> [boot_vol=<id>] [mem=<value>] [cpu=<value>] [bw=<value>] [--external_iface] [user=<username>] [pwd=<password>] [--force]

Common parameters:

Option	Description
`<class>`	The name of the AppLogic appliance class that will be created. It can be specified either as a singleton (i.e. `my_app:MYCLASS`) or as a catalog class (i.e. `/user:MYCLASS`). If the class is given as a singleton, the application is created if it does not exist. This parameter is mandatory.
`<image>`	The image to be imported. This is either the name of the image on the grid's impex volume (i.e. `my-appliance.ova`) or a URL (i.e. `https://my-server.com/my-appliance.ova`). This parameter is mandatory.
`--managed`	Create a managed appliance that sends success/failure events on appliance start & stop, automatically configures the virtual network interfaces that corresponds to terminals, has resource and performance counters that are collected and sent out the mon terminal (if present and connected), has property settings, which values are retrieved on appliance start and made available for configuration scripts.
`--unmanaged`	Create an unmanaged appliance. No modifications are done to the appliance volumes.
`--upgrade`	Replace the volumes of the specified existing `<class>` with those from `<image>`. The original volumes of the appliance class are overwritten (upon failure the old volumes are restored). The descriptor of `<class>` is not modified during an upgrade. If the existing `<class>` is managed, the imported boot volume is modified accordingly so that the class remains managed after the import is complete. This option will fail if the number of volumes in `<class>` is different than the number of volumes in `<image>`. To override this behavior, use the `--force` parameter. This parameter cannot be used with either the `--managed` or the `--unmanaged` parameter.
`user=<username>`	The username used to authenticate with a web server if the `<image>` parameter is specified as a URL. The username is also used when retrieving additional files as part of the import. This parameter is optional.
`pwd=<password>`	The password used to authenticate with a web server if the `<image>` parameter is specified as a URL. The password is also used when retrieving additional files as part of the import. If <password> is specified as `-`, `image2class` will prompt the user for the password. If standard input 'stdin' is not a terminal device, a prompt is not displayed and one copy of the password is expected as input to 'stdin' (this can be used for batch operations, to set the password from a script). This parameter is optional.
`--force`	Do not prompt for user confirmation when `<class>` already exists (with or without `--upgrade` being specified). Also, do not fail on upgrade when `<class>` has a different number of volumes than the existing `<image>` (instead update the descriptor for `<class>` so that it contains the volumes present in `<image>`). This parameter is optional.

Appliance Boundary parameters:

Option	Description
`boot_vol=<id>`	When used with an OVF image, specifies which volume to configure as the boot volume. This could either be a disk id as specified in the ovf descriptor or a number between 1 and 4 in the ordered list of volumes in the .ovf descriptor. If this parameter is not specified, the first volume is configured as the boot volume. If the specified volume does not exist, the operation will fail. This parameter is optional.
`cpu=<value>` `mem=<value>` `bw=<value>`	CPU, Memory, and bandwidth resources to be set on the boundary of the created AppLogic appliance class. Minimum, maximum and default resources are set to the same value. If not specified as a parameter and the `<image>` contains a configuration for the resources, the values for `cpu` and `mem` are taken from the `<image>`. If a resource is not specified either as a parameter or in the `<image>`, the following values are used: memory=512M, cpu=1.0, bw=100Mbps. These parameters are optional.
`--external_iface`	Enable the external interface for the created class. The network configuration must be created manually and is not handled by this utility. This parameter is optional.

Examples:

Import an OVA image from the grid's impex volume as an unmanaged singleton class:
util image2class my_app:TOMCAT tomcat.ova --unmanaged

Import an OVA image from a URL, creating a managed catalog class, overriding resources specified in the .ovf descriptor:
util image2class /proto:TOMCAT http://example.com/tomcat.ova user=some-user pwd=- --managed cpu=2 mem=512M

Upgrade a managed catalog class by replacing its volumes with those from an OVA image:
util image2class /proto:TOMCAT tomcat.ova --upgrade

Limitations

Managed Appliances

In order to create a managed AppLogic appliance from the specified virtual machine image, the image must conform to the following requirements (or else the import will fail):

Disk volumes should not be created using Logical Volume Management (LVM). Attempts to import a virtual machine with LVM-based volumes will fail with the following error message: Mount of src volume failed.
openssh-server or similar should be installed and operational; it needs to be automatically started on boot and configured to allow for root public key authentication.
The iproute2 utility should be installed and operational.
The dhclient utility should be installed and operational.
The wget utility should be installed and operational.
For Ubuntu appliances, NetworkManager should be disabled/removed.
For 64-bit Linux-based appliances, the libc6-i386 package should be installed.

General limitations of `image2class`

Only Debian and Redhat based Linux distros are supported (future updates to image2class will support other types of OSes).
User interaction is required when creating a managed appliance.
After the APK installation is complete, user logins are disabled. Access to a managed appliance is typically done by using ssh public key authentication.
image2class currently supports only OVA files (single-file OVF packaging) containing a definition of a single virtual machine. OVA files which specify multiple virtual machines are not supported.
An imported image may have a maximum number of 4 volumes.
Only raw disk volumes are supported.

Operation

Importing an OVF virtual machine as an AppLogic appliance

The image2class utility creates a new AppLogic class from an OVA packaged appliance by performing the following steps:

The OVA package digest and signature are verified (if present).
If the AppLogic appliance class is specified as a singleton (i.e. my_app:MYCLASS), the application and singleton are created. Otherwise a temporary application is created with a singleton in it.
The volumes from the OVA package are added to the singleton class. No modifications are made to the volumes at this point.
The singleton class configuration is modified as follows:
- Volumes are set to be rw, instantiable. The first volume in the .ovf descriptor, or the one specified by the boot_vol=<id> parameter, is marked as the boot volume.
- The console is set to ssh:22,text, the most common setting for AppLogic appliances. This indicates that the appliance provides ssh access through its default interface.
- The category is set to "image2class"
- CPU, Memory and Bandwidth resources are configured. Minimum, maximum and default resource assignments are all set to the same value. If specified, the values of command line parameters are used. Otherwise, the values from the .ovf descriptor are used. If no value is present in the ovf descriptor, and a value is not specified as a command line parameter, then the following values are used:
  - CPU: 1.0
  - Memory: 512M
  - Bandwidth: 100Mbps
- A default network interface is added. If the --external_iface option is given, an external interface is also added. No additional terminals are created on the class boundary. Network configuration from the OVF descriptor is ignored.
- Properties from the OVF descriptor are added to the AppLogic class. As required, property names are modified to conform to AppLogic naming conventions (i.e. unsupported characters are replaced so that ip.address becomes ip_address).
- The description and document URL are set from the configuration in the .ovf file.
If the --managed option is specified, the hvm2pv utility is executed to convert the singleton into a managed AppLogic appliance class. See the hvm2pv reference for details.
If the class option is specified as a catalog class (i.e. /user:MYCLASS), the singleton is moved to the specified catalog and can then be used as a regular AppLogic appliance class.