Class Editor -- Simple Appliances

The Class Editor property sheet allows you to define the boundary of an appliance class and set the bindings between the class boundary and the appliance internals.

To reach the Class Editor property sheet in the editor: select an appliance shape on the canvas, open the right-click menu and select Edit Class or View Class.

The class editor is organized in 6 sections (tabs):

Notes:

• The descriptions here are written assuming you understand the concepts described in the AppLogic Overview. Short definitions of some terms are also available in the Glossary.

• AppLogic has different class editors for simple appliances and for assemblies. It automatically selects the appropriate class editor based on the type of appliance you edit. The class editor for assemblies is described in Class Editor - Assemblies.

• The class editor is read-only for catalog classes. See Branching Classes for details on how to customize an existing class or create a new singleton class using the New Singletons section in the editor catalog.

General

The General tab describes the appliance class as a whole and also contains some advanced settings.

General attributes

Name

Class name. Defines the name of the appliance class. This name is shown in the bottom left side of each appliance shape on the canvas. If the appliance is placed in a catalog, the class name is also shown in the catalog. The name is a single word, case-sensitive, alphanumeric ([A-Za-z0-9_]).

Category

Category of the appliance. The category is a short alphanumeric phrase describing the group (category) of appliances within a catalog that the appliance belongs to. If the appliance is placed in a catalog, all appliances from the same category are grouped together in a section.

Description

Free text description of the appliance. Typically the description contains definition of the appliance's function, some distinguishing details (separating an appliance from other similar appliances), as well as the key software package(s) used inside the appliance.

OS

Defines the operating system, which the appliance uses. Currently only Linux is defined as available option.

Visual attributes

The following attributes determine the visual appearance of the appliance shape:

Color

The color of the appliance shape, as shown on the canvas and in the catalog.

Size

The width of the appliance shape when shown on the canvas.

It is useful to keep color choices consistent by appliance category -- this makes completed applications look better.
It is recommended to use shape size proportional to the importance and complexity of the appliance.
The height of the appliance adjusts automatically based on the number of terminals.

Advanced attributes

The following attributes determine special and diagnostic features for the appliance class.

Kernel Path

Path to the file containing the OS kernel on the appliance boot volume. The path is relative to the boot volume root directory. A kernel path must be provided; otherwise the appliance will cannot start.
All appliances provided with this release of Applogic use /boot/vmlinuz-2.6.11.10-xenU. See Appliance Creation Guide for more details on choosing the correct kernel.

Initrd Path

Path to the file containing the boot initrd image on the appliance boot volume. This path is relative to the boot volume root directory. The initrd path is optional; however, some appliances cannot boot without it.
All appliances provided with this release of Applogic use /boot/initrd-fc3.img. See Appliance Creation Guide for more details on choosing the correct initrd image.

Kernel Command Line

Additional parameters to be specified on the kernel command line when the appliance boots. This setting can be used to pass parameters to high-level drivers running in the appliance, such as file systems and network stacks. For Linux appliances, the kernel command line syntax is space-separated param=value pairs. This setting is optional and is usually empty.

Boot Timeout

The default value of the boot timeout for the appliance -- the time, in seconds, that AppLogic allows the appliance between the start of boot and the moment the appliance needs to indicate to AppLogic that it has completed boot and is operational. See Appliance Creation Guide for details. We recommend that you leave this setting empty, so that AppLogic will use the system-wide default timeout.

Field Engineering Options

This is a numeric value that enables diagnostic or other special features of AppLogic for the appliance class; this setting affects all instances of the appliance. For a list of available codes and precautions when using them, see Field Engineering Codes. In short, do not enable this option unless directed by a support engineer.

Comments and questions

Interfaces

The Interfaces tab defines the network interfaces for the appliance. There are two types of network interfaces:

• terminals, which are used to connect the appliance to other appliances
• raw interfaces, which are used for interacting with entities outside of the application.

Most appliances should use only terminals for their interactions (see the AppLogic Overview if this is not obvious).

Terminals

The appliance terminals are named network interfaces, through which the appliance interacts with other appliances in the same application. The terminals have direction -- input or output . The terminal direction determines whether the appliance originates connections or accepts connections.

Looking from inside an appliance, the terminal is a host name visible only to that appliance instance. The terminal name of an input terminal can be used inside the appliance to set up a listening socket for accepting connections. The terminal name of an output terminal resolves to whatever appliance is connected to the output and can be used to establish connections to that appliance.

Each input terminal can have many appliances connected to it. Each output terminal can be connected only to a single appliance. For more details see AppLogic Overview and Appliance Creation Guide.

Name

Name of the terminal, representing the role of the interface within the appliance. It is a single word, case-sensitive, alphanumeric ([A-Za-z0-9_]). Terminal names are usually lowercase and short -- 3 to 4 characters, so that they fit in the appliance terminal shape.

Direction

Direction of the terminal: input or output. The direction determines whether the appliance originates connections (client-side of most protocols) or accepts connections (server-side of most protocols). The direction determines only where the connection originates from; the appliance can pass data in and out of any terminal.

Protocol

Application-level (layer 7) protocol that will be used for connections on this terminal. Selecting the correct protocol allows AppLogic to enforce certain aspects of the communication and, more importantly, to provide protocol-specific statistics, such as response time for the traffic passing through the terminal. In case the appliance is protocol-agnostic, select Any. To define new protocols, see the Protocols? tab on the Application Configuration? property sheet.
In this release, this setting is ignored; however, if you configure it correctly, you will be able to use the advanced connection features when they become available.

Alias

Alias of the terminal name that can be used inside the appliance to refer to the terminal. The alias can be any valid DNS name (RFC 1035). That DNS name will be available inside the appliance as an alias to the terminal name. Aliases are useful when some application inside the appliance is hard-coded to access an external service via fixed host name (e.g., server1.mycompany.com). The alias attribute is available only for output terminals.

Options

Optional terminal attributes that can be set on the terminal:
The mandatory attribute marks the terminal as mandatory to connect for normal operation of the appliance. Typically inputs are non-mandatory and outputs are mandatory.
The switch-sides button makes the terminal appear on the other side of the appliance shape. It is useful for feedback terminals whose connection direction goes opposite to the general left-to-right flow. This attribute affects only the visual appearance, it has no runtime impact.
The gateway attribute makes an output terminal a default gateway interface for the appliance. A gateway output allows the appliance to access multiple hosts and resolve DNS names through that output. Typically, gateway outputs are used to connect appliances to the subnet gateway appliance ([GatewayOutNet][NET]]). Only one output of an appliance can be selected as a gateway. Most appliances don't have gateway outputs.

The order of the terminals in the list, as well as in the appliance shape, can be modified by selecting a terminal entry in the list and using the up and down arrow buttons on the right side of the list. This is especially useful for appliances that have more than one terminal on one of the sides.

If a mandatory terminal is not connected, the application will not start. This ensures that configuration constraints are met and prevents many configuration errors from happening. AppLogic will report the name of the appliance and the terminal that failed the check, so that you can easily locate and fix it.

Raw Interfaces

The raw interfaces allow the appliance to interact with entities outside of the application.

External Interface

This option enables the appliance to interact with other applications and with any host accessible on the network (external interactions). In hosted AppLogic environments, the external interface has access to the Internet, so make sure the appliance is properly firewalled and otherwise protected if you enable the external interface. The appliance is responsible to fully configure the external interface, including its IP address, gateway, etc. See the Appliance Creation Guide for more details. Typically, only gateway appliances need to have the external interface enabled.
If in doubt, keep the external interface disabled (and contact Technical Support for discussion).

Default Interface

This option allows the appliance to interface with the AppLogic system, specifically permitting authorized secure shell (ssh) connections to the appliance.
In this release the default interface cannot be disabled, since it is used by appliances to report that they have started. Even if you uncheck this option, the default interface will be enabled.

Comments and questions

Volumes

The Volumes tab allows you to create and destroy the set of volumes required for the operation of the appliance.

For each volume, the following fields are defined:

Name

Logical name of the volume within the appliance. This name represents the role of the volume for the appliance class. It is a single word, case-sensitive, alphanumeric ([A-Za-z0-9_]).

Mount on

Name of a device, on which AppLogic makes the volume available to the appliance. For Linux appliances this is typically in the form of /dev/hdaN, where N is a digit between 1 and 9. The appliance itself determines in its /etc/fstab configuration file how and where in the filesystem hierarchy the volume is mounted.

Boot

Determines the boot volume for the appliance. Each appliance MUST have a boot volume, otherwise it will not start. See the Appliance Creation Guide for more information on how to create an appliance boot volume.

Type

Volume type. AppLogic supports the following volume types:

• Instantiable : A class volume of the appliance that needs to be instantiated for each appliance instance. AppLogic makes a separate copy of such volumes for each instance of the appliance. Most boot volumes are of this type. Press button to create a new volume.
• Placeholder : A placeholder for a volume that can be configured with an application volume for the appliance instance. The appliance class itself does not carry the volume. Each appliance instance is configured explicitly with a volume from the application. Most content, data and code-containing volumes are of this type.
• Common : This type of class volume is shared between all instances of the appliance class. All instances access the same volume and it must be read-only. No separate copy of the volume is made.
  This volume type is useful for large read-only data sets that are not used heavily.
• Blank : An empty volume, that will be created for each appliance instance.
  The blank volume type is similar to the instantiable volume type, except that no template volume exists for the class and instance volumes are created empty (unformatted). This type of volumes may be useful for appliances that hold user data (like database and other).

Size

Volume size for blank volumes. This field defines the size of the volume that AppLogic will create. The size is specified as integer with optional M or G suffix (e.g., 256M). This field is shown and needed only for volumes of type blank. For all other volumes, AppLogic gets the volume size from the volumes themselves.

Constraints

Performance constraints for the volume. AppLogic supports three volume constraints: none, high bandwidth and local only. For volumes requiring high-bandwitdh access, AppLogic tries to schedule the appliance on the same server where the volume resides. If this is not possible, AppLogic logs a warning but it nevertheless runs the application. For volumes set here as requiring local-only access, AppLogic will not start the application unless it can ensure that the appliance can run on the same server where the volume is.

Options

A set of important volume options described below.
The mandatory attribute makes the placeholder volumes required (currently all volumes are required, so this attribute is not used).
The read-only attribute makes the volume read-only (write-protected) for the appliance
The shared attribute marks the volume as shareable between appliances (see a number of cautions below)
The create-volume button allows you to create the volume. This selection is needed for all instantiable and common volumes. See the Appliance Creation Guide for details.
The destroy-volume button allows you to destroy the volume.

It is the responsibility of the appliance to mount a volume itself whenever it needs it in the file system and needs to select the r/o or r/w option on the mount within /etc/fstab to specify the type of access to the file system. The R/O vs. R/W setting in the editor does not affect how the appliance mounts the volume but only how it can mount it. For example, if a volume is specified as R/O in the editor then the appliance can only mount the volume as R/O. However, if the volume is specified as R/W in the editor, the appliance may mount the volume as R/O or R/W.

Cautions:

• don't make a volume shared unless it is also read-only (shared r/w access will corrupt the filesystem)
• don't make boot volumes read-only unless you have configured the boot volume specifically for this
• when making a volume read-only, make sure that /etc/fstab is properly configured for read-only mount
• when designing the set of volumes for appliances, keep the user data on a placeholder volume
• when possible, use instantiable volumes instead of blank volumes -- they are easier

Combining the read-only and shared attributes allows you to share read-only volumes between appliances. Further, you can define properties to configure root directories, so that multiple appliances can use the same volume to obtain different file sets from it (e.g., HTML content, application code, etc.)

You can arrange the order of the volumes in the list using the up and down arrows. The order affects only how the volumes will be shown to you in the property sheets; it has no runtime impact.

Comments and questions

Properties

The Properties tab defines the properties that will be available on the appliances of this class. Properties are named configuration parameters for the appliance.

Defining Properties

AppLogic supports three property types: string, integer and IP address. You can make a property mandatory, requiring that its value be explicitly set on each instance. Alternatively, you can define a default value for the property and that value will be used, if no special value is configured on an appliance instance.

The set of properties on an appliance class reflects the specific needs of the class. AppLogic passes the property values to the appliance without interpretation. You are free to define whatever properties you like.

Name

Name for the property. The property name uniquely identifies a property within the appliance. The property names are used to set property values in the Instance Settings property sheet. The property names are also used inside the appliance to match the property values to configuration parameters (see Appliance Creation Guide for details).

Type

Type of the property. AppLogic supports three property types: string, integer and IP address. The type constraints the possible property values (for other constraints options, see below).

Default

Default value for the property. This value will be used if no value is specifically defined for the property in an appliance instance. Most properties should have defaults. You can leave the default value empty, in which case the default is an empty string. You can also disable the default value by making the property mandatory (see below).

Options

Optional property attributes include the following:
The mandatory attribute marks the property as required to be set specifically on each appliance instance, making it so that the property has no defaults. Having a lot of mandatory properties makes it hard to use the appliance, so keep them to a minimum. Mandatory properties should be used only in cases where no default can be defined (e.g., the target host name in output gateways).
The constraints button opens a separate window, shown below that allows you to define value constraints for the property.
The lowercase attribute makes the property values not case sensitive. No matter what letter case is used in for property values in the instances, the values will be lowercased by AppLogic when provided to the appliance. This attribute is useful for things like DNS names and for properties that have pre-defined list of values (see below).

Info

In addition, pressing the info button provides a summary of the property attributes. This is a quick way to see any constraints without opening the constraints window.

You can arrange the property order in the list by using the up and down buttons on the right side of the list. We recommend using the property order to make configuration more intuitive: group the more important properties at the top; arrange the properties in the order in which it will make sense to configure them (e.g., IP address, netmask and then gateway).

Property Constraints

If you want to define value constraints for a property, press the constraints button . This will open the constraints setup window:

AppLogic supports three types of constraints:

Min - Max

The min-max (range) constraint allows setting a minimum and a maximum value for integer properties. To limit only on one side of the range, leave the other side empty (i.e., specify only the minimum or only the maximum).

Filter

The filter constraint allows setting a regular expression for validating the property value. Regular expressions are fickle (very error prone), so use this constraint with care -- or simply use the values constraint instead. The syntax of the filter is the same as the Perl regular expression pattern matching (http://perldoc.perl.org/perlre.html). AppLogic performs the match on the entire property value - that is as if /^filter$/ was used in a Perl statement to check for a match (where filter is the value of the filter attribute). You can use the filter constraint with any property type.

Values

The values constraint allows you to define an enumerated set of values for the property, limiting the possible property values. The syntax is regular expression-like: literal values separated with vertical bar (|). For example, any|tcp|udp allows only any, tcp or udp as values for the property. You can use the filter constraint with any property type. For string properties, you can use the values constraint together with the lowercase property attribute to make the value set not case sensitive.

If a mandatory property is not set or a property value constraints are not met, the application will not start. This ensures that configuration constraints are met and prevents many configuration errors from happening. AppLogic will report the name of the appliance and the property that failed the constraint check, so that you can easily locate and fix it.

Comments and questions

Config Files

The Configuration Files property sheet lets you define a set of files on the appliance volumes that you want AppLogic to modify. All property values set on the appliance instance will propagate to these files. Such files, for example, would be httpd.conf for Apache web server appliance, my.cnf for MySQL database appliance, etc.

For each configuration file you want AppLogic to modify, add an entry in this list.

Volume

The appliance volume where the configuration file resides. Typically this is the boot volume, but in some cases you may want to have the a configuration file on a data volume. AppLogic can modify config files on instantiable and placeholder volumes that are not read-only.

Path

The path to the configuration file that needs to be modified, relative to the root of the volume. For example, this may be /etc/my.cnf for MySQL's config file.

Quoting Method

The method that AppLogic will use to quote meta-characters in the value. A "meta-character" is any character that has a special meaning in the config file and must be quoted (or "escaped") in some manner in order to appear as a data character and not in its special-function role. Based on the type of configuration file you have, the quoting method can be set to one of the following values:

• None or Conf - no quoting (default). The value is stored in the config file as is.
• Bash, Perl or C - data values that are enclosed by quotes are assumed to use \" to mean the quote character and \\ to mean the backslash. Backslashes that don't quote a " or \ character are left untouched, i.e., if you set a property value to "abc\def"ghi\n", the result written into the config file is "abc\\def\"ghi\n". Values that are not surrounded by quotes are limited to alphanumeric characters. Aan error is reported if such a property is set to a value with other characters, even if the filter for that property allows it.
• HTML - the characters that have significance in the HTML syntax (< > " and &) are encoded as &lt; &gt; &quot and &amp;. For example, abc&def<ghi becomes abc&amp;def&lt;ghi in the config file.

You can change the order in the list by selecting an entry and using the up and down buttons on the right side of the list.

In order for AppLogic to properly modify the configuration files and know where to apply the instance property values, you need to have those configuration files instrumented using the Property Markup Syntax. See the Appliance Creation Guide for more details.

In addition to configuration files you add here, AppLogic also puts all property values in a small shell script file called /etc/applogic.sh. You can use that file from shell scripts via the source /etc/applogic.sh command. See the Appliance Creation Guide for more details.

Comments and questions

Resources

The Resources tab allows you to specify the amount of hardware resources that are needed for each instance of this appliance. You can select amount of CPU (percentage of a full CPU), memory and bandwidth needed by the appliance.

Resource types and specification

The following resource types can be specified:

CPU

Portion of a CPU to be allocated for each instance. Portions can be specified as percentage (e.g., 10%) or as a decimal number (0.10).
In this version of AppLogic, the maximum amount of CPU for a simple appliance is 100% or 1.0.

Memory

Amount of memory to be allocated for each instance. The amount can be specified as an integer value in Megabytes (e.g., 128M) or in Gigabytes (e.g., 2G). For 32-bit Linux appliances, the memory should be at least 32M and no more than 3G.

Bandwidth

Amount of network bandwidth to be allocated for each instance (total for all terminals/interfaces). The amount can be specified as an integer value in Megabits/sec (e.g., 10M) or in Gigabits/sec (e.g., 1G). The maximum amount of bandwidth for a simple appliance is 2G (a full duplex Gigabit Ethernet port).

Resource ranges

You can specify a range for each resource type. The range defines the normal operating parameters desired for the appliance, as well as minimum resource requirements for sandbox use.

Minimum

The absolute minimum amount of a resource that the appliance needs to work at all. This is useful to allow running the appliance in functional testing environments, where the appliance is not expected to run under production load and can run with much less resources. Contrast this with the Default below, which is amount of resources needed for production use.

Maximum

The maximum amount of a resource that the appliance will be allowed to take. Typically this is the maximum that an appliance can use (i.e., giving it more resoucres will not increase performance). The appliance will not be allocated more than the specified maximum amount, ensuring that the appliance will not be able to take resources away from other appliances -- think of it as a quota.

Default

The minimum amount of a resource that the appliance requires for normal operation in production environments. The appliance will not be started unless at least that much can be allocated for it (likely failing the start of the application as a whole). Specifying a minimum ensures that the appliance will work within certain "guaranteed" resource amount -- think of it as a service level agreement (SLA) for that resource.

Notes

Leave the broadest reasonable range for all resources. The amount of resources actually allocated for an instance of the appliance can be further constrained by the instance settings of the appliance.

The degree, to which the resource ranges are enforced varies, based on the underlying virtualization technology used by AppLogic.
In this release, the CPU minimum is guaranteed and the maximum is enforced only if other appliances need the CPU; the memory minimum and maximum are strictly enforced; the bandwidth minimum and maximum are not enforced at all -- they are used only in order to make scheduling decisions. As a result, it is guaranteed that an appliance will get its minimum CPU and memory. It may not get its full bandwidth, if another appliance is scheduled on the same server and hogs the bandwidth. We expect the bandwidth guarantee to be provided in a future version. In the meantime, we can help devising a solution for particular problems you may have with this limitation (see Technical Support).

Comments and questions

test

-- Main.PeterNic - 18 Mar 2007

-- BeckyH - 25 May 2006