How to upgrade your applications to use the new appliance kit (APK)

Appliances created prior to AppLogic 2.3 use the volfix mode of configuration. When starting an appliance that uses the volfix mode, AppLogic mounts its boot volume on the grid controller in order to update the appliance's configuration (properties, network settings, etc). Beginning with AppLogic 2.3, appliances can make use of the new DHCP configuration mode which depricates the volfix mode. When using the DHCP mode, an appliance configures itself through its default interface which results in greater reliability, is more flexible and improves significantly the application's starting time. Using the DHCP mode also cuts down on the amount of I/O generated by the grid controller.

This document describes how to upgrade your AppLogic appliances and applications to use the new DHCP configuration mode. It is divided into 2 sections. The first section describes how to upgrade an appliance to use the new DHCP configuration mode. The second section describes how to upgrade your application to use the newly upgraded appliances. It is recommended to read through this entire document before trying to upgrade your appliances and applications.

Upgrading an appliance to use the DHCP configuration mode

Follow the instructions below to upgrade an existing Linux appliance from volfix to DHCP configuration mode (either a catalog class or singleton).

1. Make an application containing a singleton copy of the appliance to be upgraded:
   • If the appliance is in a catalog, create a new application containing an instance of the catalog class and branch the instance to create a singleton.
   • If the appliance is a singleton:
     • If the application containing the singleton is running, the application must be stopped.
     • Copy the application that contains the singleton using the app copy command. The singleton should be upgraded in its own application so in case something goes wrong the original singleton is preserved. All of the remaining steps in this section should be executed over the new copy of the application.
     • Note: If you do not want to make a copy of the application because it has very large volumes, you can convert the singleton into a catalog class and instantiate an instance of that class in a new application.
2. In the new application, connect the singleton to a NET appliance to obtain external network access (this is only needed if your appliance does not have its external interface enabled and configured):
   • If necessary add a net terminal to the singleton in the AppLogic editor and mark this terminal as a gateway interface in the appliance boundary
   • Connect the net terminal of the singleton to the in terminal of the NET appliance instance
   • Configure the NET appliance with the appropriate network settings
3. If the singleton has a read-only boot volume or any of its boot volume folders (i.e., /usr) residing on common, read-only volumes, these volumes must be converted to read-write. This is needed since the installation of various packages on the appliance may require updates to these volumes:
   • Open the new application in the AppLogic GUI. Right-click on the singleton and select the "Modify Boundary" menu item.
   • Select the "Volumes" tab.
   • Look at both the "Type" and "Options" columns and see if there are any common, read-only volumes. If there are no volumes of this type go to the next step.
   • For all of the common, read-only volumes, unselect the read-only button (the read-only button has a picture of glasses).
4. Configure all mandatory properties and volumes of the singleton and start the application in debug mode (using the --debug option).
5. Install the dhclient package on the singleton (this is a dependency of APK). For example, on a CentOS based appliance:
   • ssh into the running singleton appliance
   • Execute: yum install dhclient
6. Copy the appropriate APK to /tmp in the running singleton:
   • Obtain the IP address of the DHCP server for the internal interface of the singleton appliance:
     • Within the appliance shell execute ifconfig -a and note the broadcast subnet of the last enumerated network interface, e.g. 10.47.255.255. The IP address for the DHCP server is identical except for the last number which is 254, e.g. 10.47.255.254. If the broadcast subnet does not list a usable address, you must execute the following 2 steps:
       • Execute dhclient -r ethX where X is the number of the last enumerated network interface (removes the DHCP lease just in case)
       • Execute dhclient ethX and note the IP address from which DHCPOFFER is made
   • Use wget to download the appropriate APK into your appliance:
     • wget http://10.47.255.254:8080/download (this downloads index.html which contains the list of files that are downloadable from the grid controller; you may also use a text-based browser for convenience)
     • cat index.html; note the latest version of the APK package (e.g., apk-2.0.20-linux-rh.tar.gz; 2.0.20 is the latest version as of AppLogic 2.7)
     • cd /tmp
     • wget http://10.47.255.254:8080/download/apk-2.0.20-linux-rh.tar.gz (be sure to use the correct IP and APK package)
     • cd /
7. Follow the appropriate APK installation instructions. It should not be necessary to replace the domU kernel. Do not delete the /appliance directory.
   • If upgrading a CentOS-based appliance, execute the following:
     • cd /
     • mv /appliance /appliance_save
     • tmp/apk-install
     • rm -f /tmp/apk-install /tmp/apk-2.0.18-linux-rh.tar.gz
     • mv /appliance_save /appliance
     • mkdir /var/log/appliance
   • For other OSes besides CentOS, see APK Installation for RedHat Distributions or APK Installation for Ubuntu Distributions for detailed instructions
8. If the singleton ordinarily allows for password based ssh authentication (e.g., as in a VDS application singleton), edit /etc/ssh/sshd_config and modify the following:
   • Change PermitRootLogin without-password to PermitRootLogin yes
   • Remove ChallengeResponseAuthentication no
9. To make the original /appliance/appliance.sh script execute on appliance start:
   • Create a file /etc/sysconfig/applogic_appliance with mode 644 which contains the following text: /appliance/appliance.sh $@
10. In the AppLogic application editor, view the singleton boundary and note any files listed in the Config Files tab, e.g. /etc/httpd/conf.d/appl.conf
    • If there are no config files listed on this tab, go to the next step.
    • In your appliance, create a file /etc/sysconfig/applogic_init with mode 644 containing a space separated list of config files (surrounded by double quotes), e.g.:
      • APK_CONFIG_FILES="/etc/httpd/conf.d/appl.conf /etc/httpd/conf.d/bnna.conf"
11. Stop the application. In the AppLogic editor modify the singleton boundary:
    • In the Config Files tab delete all entries
    • In the General tab click the Virtualization Mode Options button and do the following:
      • Clear the Kernel Path and Initrd Path entries
      • Change the Configuration Mode from volfix to dhcp
    • Save the application
12. Start the application in debug mode (using the --debug option). It should start without error. If starting the app fails, examine the grid controller system log for details (log list). Test the appliance to make sure it works.
13. If the upgraded appliance had common, read-only volumes that were converted to read-write in step 3, please make sure the volumes are converted back to read-only.
14. Your appliance is now upgraded to use the APK and the DHCP configuration mode. If your upgraded appliance is a singleton, the upgrade process is complete. If your appliance is a catalog class, please see the next section on how to upgrade your AppLogic applications to use the upgraded appliance.

Upgrading applications to use your new DHCP-based appliances

There are 2 different options available for upgrading your applications to use your new DHCP-based appliances. These options depend on the number of applications that need to be upgraded and the amount of downtime that can be afforded.

Minimal downtime: one application at a time

1. Change the name of the class for the upgraded singleton so it is different than the original class name.
2. Drag the upgraded singleton into the /user catalog (or another catalog of your choice; we assume /user for the remaining steps).
3. Open the application that needs to be updated with the newly upgraded class.
4. Drag-and-drop the new appliance class over the old instances in your application while holding down the Shift key (this will update the instance to use the new class and preserves all configuration settings).
5. Re-start the application and verify it is operational.
6. Repeat these steps for each application you wish to upgrade.

Downtime is not critical: all applications at the same time

1. Stop all applications that use the appliance that was upgraded in the previous section.
2. Rename the old appliance class: Right-click on the class and choose the rename option in the AppLogic GUI.
3. Drag the upgraded singleton into the same catalog where the appliance came from originally.
4. Restart all of the applications that were stopped in the first step.

-- StephenQ - 04 May 2009