June 17 - AppLogic 2.3.9 beta is now available! The latest production release is AppLogic 2.1.1

---

Appliance Creation Guide

This document describes how to create a new appliance starting from templates or other appliances provided in AppLogic.

If you want to build appliances from scratch -- from your own Linux image -- please contact TechnicalSupport for the latest information.

Design a boundary

See the catalog reference for examples.

Specifically, think of the following:

• class name for the new appliance
• set of terminals (inputs and outputs)
• user volumes (if the appliance needs to store user data)
• set of properties you may want to configure on each instance
• typical usage

If there is an appliance with similar characteristics in the global catalog or in installed applications, look at that boundary for ideas.

Choose a template

AppLogic provides two generic templates:

• LUX - a small template for Linux-based appliances
• LINUX - a larger template for application and other Linux-based servers

The LUX appliance has a 200 MB volume with a minimum installation of Linux. It doesn't have man pages or the GCC compiler. Choose this template if you can install your custom software as a binary image (e.g., RPM). Since LUX doesn't have a lot of free space, you may copy it to a larger volume (see troubleshooting below).

The LINUX server has a 2 GB volume with a regular, server installation of Linux. Choose this template if your software is available only in source form, or you will frequently need to log in and install/configure additional software.

If there is an existing appliance that is similar to what you need, use it instead of the generic templates. For example, if you are building a clustered MySQL appliance, you may be better off starting from the MYSQL appliance than from the LUX appliance.

Create a singleton

Once you have selected the template, you will create a new singleton class for your appliance.

This step involves the following:

1. Create a new application (or use an application you already have, like the sample app)
2. Drag the template chosen in the previous step from the global catalog onto the canvas
3. Branch the template class (right-click on the instance shape on the canvas and choose Branch Class)
4. When prompted, confirm that it is OK to save the application; wait until the branch operation completes and reloads the application

When you try to branch the class, if you get a second warning window saying that there is no instance volume already copied, select OK to proceed. In this case, the branch process may take a few minutes, as AppLogic is making copies of the appliance volume.

Configure the new singleton to require a minimum of 128M of memory to run, even if the software planned for installation does not need this much. The resource requirement can be changed later when the installation of software on the new appliance is completed, however it is critical to have the extra memory during installation, because the base appliance images (like LUX) do not have swapping enabled and package installers need a lot of memory to work. In particular, yum is known not to work with less than 96Mb of system memory.

You now have a singleton class ready for customization.

Configure the appliance boundary

Set up the appliance to the designed boundary.

1. Select the newly minted appliance. Right-click on its shape and choose Edit Class.
2. Change the class name to your chosen name for the appliance class.
3. Review other options on the General tab, in particular the size and color.
4. Make the changes needed on the Interfaces tab to match the set of terminals in the designed boundary
5. Make sure the default interface is checked and the external interface is not checked (see below for using the external interface.
6. If your appliance needs user volumes, add them on the Volumes tab. Carefully choose the read-only and shared options -- usually they are either both off (read-write non-shared) or both on (read-only shared).
7. Add the properties on the Properties tab. Make sure you have selected good defaults; mark properties that cannot have defaults as mandatory. Set property constraints, if needed.
8. Review the Config Files and Resources tabs. If nothing sticks out as wrong, leave them alone -- you will return to them later. Specifically, don't add any config files that don't already exist on the volume, because this will prevent the appliance from starting.
9. Save your changes.

If you plan to install new software on the appliance, in a sub-directory of the /usr directory, make sure that the appliance common volume (named usr) is made writeable and non-shared (unclick the read-only and shared buttons in the Volumes tab of the class editor). This will allow you to write to the usr volume. (Before moving the appliance to the catalog, you will need to make the common volume read-only and shared again.)

Once you have set the boundary correctly, define instance settings for the instance in the test application, so that you can start the application:

• if your appliance has mandatory properties, make sure you have set values for them (using Editor Instance Settings, Property Values tab)
• if your appliance has mandatory terminals, make sure they are connected (e.g., to spare instances of LUX or LINUX)
• if your appliance has user volumes, make sure you have configured them (using Editor Instance Settings, User Volumes tab)

How you create application volumes is described in Editor Manage Volumes.

To verify that everything still works, try to start the application.

Install and configure the appliance

There are two key steps here.

First, get the software you want to install to the appliance boot volume. Second, install the software and configure it.

The easiest way to do that is the following:

1. Copy the software distribution (e.g., rpm) that you will install to the AppLogic controller volume (e.g., in your home directory).
2. Start the test application.
3. Find the IP address of your appliance's default interface (use the component info shell command)
4. Using scp (ssh-based secure copy), copy the software distribution to the appliance. Make sure you are using the private ssh key for the copy (appliances don't allow password based logins).
   • use the IP address found in the previous step as IP of the appliance
   • example: scp myfiles.tar.gz root@10.50.12.14:/usr/local
   • if you are not running ssh-agent, you will want to specify the appliances private key file (-i rsa_appliance option after scp)
5. Login to the appliance via ssh (using the ssh command from the controller shell).
6. Install the software on the appliance
7. Configure the software, instrument any configuration files (see Class Editor and ADL Property Markup)
8. If your appliance has heavy incoming UDP traffic (e.g., VoIP? appliance), please read the note at SCR 487 to avoid excessive packet drop.
9. Verify that the appliance works when started from scratch (stop the application and restart it, see everything starts and works properly).
10. If you want, run prelink and rpmpkgs in order to pre-link any new shared objects and record the installed RPM versions, respectively. If you expect to be logged in to the appliance frequently and need the locate command, run locate -u to update locate's index. (On regular Linux servers, these operations are performed periodically by a cron job; in AppLogic appliances these cron jobs are disabled because the appliance installations don't change for catalog classes.)

An alternate method for getting the software on to the appliance is having a (temporary) output on the appliance that is marked as a gateway output and is connected to a temporary instance of the NET gateway appliance. This way, you will have access to the Internet from the appliance and you can download various software packages directly from their distribution sites (e.g., www.sourceforge.net, fedora.redhat.com, etc.). Don't forget to remove the temporary terminal from your appliance when done with the installation.

Yet another method to put the software on the appliance is to mount its volume on the controller and copy the files. To use this method you should log in as "root" on the controller and make sure the application is not running (otherwise the appliance's volume cannot be mounted).

Review and finalize the boundary

1. In the editor, open on the class editor on the appliance (right-click, Edit Class).
2. Check the class name and the category in which you want the appliance to show up in the catalog.
3. Review all tabs, including Config Files and Resources. Make sure they have the desired values.
4. Save and start the application. Verify everything still works correctly after the changes you made (if any).

Move the appliance to a catalog

If you don't need to create multiple instances of the appliance, in your current application or in general, you may skip this section and leave the appliance as a singleton in your application. If you want to create multiple instances, however, move it to the catalog.

1. Log in on your appliance and cleanup any unnecessary files from the class volume (logs, SSH keys, bash and mysql history, etc.).
2. Log out and stop the application.
3. In the editor, select the catalog you want to put the appliance in (e.g., the global catalog (global) or the application-specific catalog (catalog)).
4. Drag the your (singleton) appliance into the catalog. Confirm when asked if OK to save the application.

Congratulations! You have added your new appliance to the catalog. Now you can instantiate the appliance in your application(s).

If the move to catalog fails saying that the common volumes of an appliance must be read-only and shared, open the class editor over the singleton appliance. Go to the Volumes tab. Make sure that all volumes of type 'Common' (usually called usr) are marked as read-only and shared. This will allow AppLogic to share the common volume between all instances of the appliance (if you don't want that, change the volume type to instantiable). Close the class editor and try to move the appliance to the catalog again.

Advanced Topics

The following topics will be added soon. If you need something here, please let us know.

• Adding Placeholder Volumes
• Enabling the External Interface
• Creating Composite Appliances (assemblies)
• Configuration File Tips and Tricks

Troubleshooting

Appliance won't start

If the appliance fails to start when you start the application, the most likely reason is that the appliance is not starting the VM agent (this is visible during start as the appliance taking a long time to start and then failing; the log says that appliance start timed out). To fix this, make sure the appliance runs the /appliance/vma_load.sh script when it is done booting. All templates from the global catalog have this script and start it by default.

In most cases, even when the appliance doesn't start (times out), you have a couple of minutes to log in on it. Here is how:

• open two ssh sessions to the controller: one from which you will start the application and one to access the appliance
• start the application from the first session
• while the application is starting, go to the second session and check the appliance status using component list shell command
• when you see your appliance in Starting state, wait 10-20 seconds and try to ssh into it (ssh).

Since the default timeout is quite short -- approximately 2 minutes -- you may want to temporarily override the boot timeout. See the General tab on the Instance Settings screen; set the timeout to 3600 seconds (1 hour). Once you troubleshoot the appliance and it begins to start OK, restore the default boot timeout.

If you cannot even ssh to the appliance, then most likely the volume or its boot configuration got corrupted. You can stop the application, mount the volume and inspect it, or start from the template again. If the problem recurs, contact Technical Support.

Appliance starts but property values are not propagated

Appliance starts OK, but all properties are left at their default values in the instrumented configuration files.

1. Check that the configuration files are listed in the Config Files tab of the class in the Class Editor.
2. Check that the configuration files are instrumented using the ADL property markup syntax

Comments

-- BeckyH - 26 May 2006