User Operations Manual

Provisioning an application

In AppLogic, application instances can be provisioned with a single command -- app provision, no matter what the application is and how complex it is. The same command is used for simple apps like cPanel or Grid Server that can run in a fraction of a server, and for complex 2- and 3-tier scalable applications that can take 20+ servers. Once the command completes, the application is fully configured and running.

When provisioning a new application, you need to choose the following:

• application template name
• desired name for the application instance
• configuration properties (IP settings, user name and password)
• resources (CPU, memory, disk size)
• billing information and comment

A typical application provisioning command looks like this:

• for grid server:

app provision VPS_CentOS50_r1 gs_cust12 \
    hostname=gs_cust12 primary_ip=209.100.100.12 \
    netmask=255.255.255.0 gateway=209.100.100.1 \
    dns1=209.101.1.2 dns=209.102.1.2 \
    user=user12 user_pw=K2RX9Jx5 root_pw=17bWvuMG \
    cpu.dflt=0.10 mem.dflt=256M GSC.boot.size=20G \
    .user1=Customer12 .user2=RatePlan2 \
    .description="grid server for customer #12"

• for SugarCRM? :

app provision SugarCRM? _r1 sugar_1
    user_ip=209.100.100.11 admin_ip=209.100.100.12 \
    netmask=255.255.255.0 gateway=209.100.100.1 \
    dns1=209.101.1.2 dns=209.102.1.2 \
    mail_server=mail@mycompany.com \
    cpu.dflt=4.0 mem.dflt=1G code.size=512M data.size=1G \
    config.size=256M logs.size=64M \
    .user1=Customer1 .user2=RatePlan5 \
    .description="SugarCRM hosing for customer #1"

• for TWiki

app provision TWiki_r1 twiki_1
    user_ip=209.100.100.11 admin_ip=209.100.100.12 \
    netmask=255.255.255.0 gateway=209.100.100.1 \
    dns1=209.101.1.2 dns=209.102.1.2 \
    mail_server=mail@mycompany.com \
    cpu.dflt=1.0 mem.dflt=256M data.size=512M twiki.size=512M \
    .user1=Customer1 .user2=RatePlan5 \
    .description="TWiki hosing for customer #1"

The app provision command starts the application. If you want to provision the application without starting it (e.g., to prepare ready instances but not start them), add the --skipstart option at the end of the app provision command line. See RefShell for all options of this command.

Template

Any application on the grid can be used as a template (as long as the application is stopped and has the template attribute set). You can see the list of applications and application templates using the app list command. The template applications are shown first in the list.

Note that the provision command copies the template in its entirety. Therefore we recommend that you not specify any application as a template that has user data on it as that data will be copied over to the newly provisioned application.

Instance name

The desired name for the application instance (aka application name) is a word consisting of letters and digits, starting with a letter. Don't use special characters, except underscore. Examples of valid names are: app23, cPanel37Beta, big_server. Examples of invalid names are: 3joe (starts with a digit), my app (has a space), bighoster.com (has a dot), cPanel/Joe (has a special char).

We recommend encoding the template name and the customer name, for example: cPanel_customer8. Applications are always displayed sorted, so applications starting with the same name will be grouped together in the list.

Properties

Properties are application-specific settings that specialize the application instance for its role. While the template provides most of the system and application configuration necessary for the application to run, there are some settings that differ from instance to instance. Those typically include IP addresses, passwords and tuning parameters.

Some properties are mandatory and must be specified with the app provision command. Other properties are optional and need to be specified only when you want to change the default values.

You can see the set of properties, their allowed values and meaning in the application template's data sheet. The application templates currently shipped with AppLogic are documented in the Application Reference. If the application is provided separately and the data sheet is missing, please ask Technical Support for its data sheet.

You can quickly inspect the properties available on the template application using the following command: app config mytemplate --boundary. For more information, please read the data sheet.

You can pre-configure any property on the template, so that you don't have to provide them every time when provisioning an instance. For example, to configure the default netmask, gateway and dns servers in the template itself, use:

app config mytemplate netmask=255.255.255.0 gateway=209.100.100.1 dns1=209.101.1.2 dns2=209.102.1.2

Resources

There are 3 types of resources that can be configured on an application during its provisioning:

• amount of CPU to be provisioned to the application
• amount of memory to be provisioned to the application
• size of its disk volumes

Although AppLogic documentation refers to the bandwidth resource as well, please don't use this parameter (it specifies internal bandwidth, not Internet bandwidth); leave the bw values to their defaults.

All of these resource parameters have reasonable defaults. If you don't want to change them, leave the defaults. You can always change them later if needed.

You can see the allowed resource ranges for your application in its template's data sheet (see RefApps). You can also find them quickly by running app config mytemplate --boundary and look at the resources section (for memory and CPU only).

The CPU is defined in fractions of a CPU (for single appliance applications) or as a fixed-decimal (for multi-appliance applications). For example, cpu.dflt=0.10 is 10% of the CPU, cpu.dflt=1.00 is a full CPU, and cpu.dflt=0.25 is 25% CPU.

The memory is defined in megabytes. For example, mem.dflt=128M defines 128 MB, and mem.dflt=1024M defines 1 GB (don't forget the M suffix).

Note: The cpu.dflt and mem.dflt parameters define the actual amount of resources the application will get. The memory will be enforced exactly (minus a few megabytes for system records). The CPU is the minimum amount the application will get if it needs it, regardless of any other applications running on the same grid and the same physical server. The application may get more CPU, up to the full CPU of the server, whenever no other applications need CPU on that server.

The size of disk volumes for the application can be left to what the template defines, or changed to any size within the range defined by the application template. The list of disk volumes and their size ranges are defined in the application's data sheet (see RefApps).

You can see the list of volumes of a template, and their current sizes, by running the vol list mytemplate --all command.

To change the disk size of an application volume during provisioning, specify the volume name and its desired size (the syntax is volume.size=size). For example:

• for grid server, to define the size of the server disk to 10 GB, use VPS_CENTOS50.boot.size=10G

Billing information and comment

These settings are optional. You can configure them with any text/values that will be useful for your operations.

There are three available fields:

• .user1: we recommend using this setting for your customer's name (for whom the application is provisioned) or their account number
• .user2: we recommend using this setting for your billing code (e.g., rate plan)
• .description: we recommend using this setting for a human-readable description of the purpose of the application instance

The description is displayed in the application list (app list --verbose) and in the browser.

The .user1 and .user2 fields are displayed by the app info myapp and app config myapp commands. These two fields, together with the application instance name, are also included in the metering information records that 3tera may provide you for all applications that run on the grid.

Configuring an application

To configure or modify the configuration of an application, use the app config command, as shown below, to change any application property.

   app stop myapp
   app config myapp primary_ip=209.100.100.12 dns1=209.101.1.3
   app start myapp

If you are changing resources and configuration properties (see below), you can combine the reconfiguration with a single stop and restart. You can even combine properties and cpu/memory resources in the same app config command.

Starting an application

Once an application has been created and configured, it can be started.

   app start myapp

Retrieving information about your application

You can retrieve various types of information about applications that are installed on the grid.

The following command displays a list of applications that are installed on the grid:

   app list

The following command displays information for an application. If the application is running, additional information is displayed:

   app info myapp

If an application is running the components may be listed with the following command:

   component list myapp

If an application is running, you can see how the components are distributed amongst the servers of the grid by executing the following command:

   server list --map

Accessing your application

If an application is running, you can access an individual component by logging into it using the following command:

   login myapp:component

If an application is running and there is a default console set for the application, you can login to that component using the following command:

   login myapp

Restarting your application

In some cases it is necessary to stop and restart the application.

   app restart myapp

For complex applications, this command restarts all appliances (stops them and restarts them in the correct order).

Copying an application

To copy an application:

• Stop the application (app stop myapp)
• Copy the application (app copy myapp mynewapp)

The copy operation copies the application code, all user data and application configuration. The copy is an application instance, so it can be started.

To start the copy:

• Start the copy (app start mynewapp)
• Delete the old app if not needed (app destroy myapp)

Note: never run the original application and the copy simultaneously, unless you have changed the IP addresses of one of them

Decommissioning an application instance

When an application instance is no longer needed, it can be simply stopped and deleted:

   app stop myapp
   app destroy myapp

The stopping and destruction of an application may also be performed with a single command app destroy. When this command is executed over a running application, the application is stopped prior to being destroyed.

   app destroy myapp

All application information is lost, including configuration settings and any user data. There is no "undelete".

Migrating an application between grids

You may want to migrate an application instance from one grid to another. For example, an application may need to be migrated because:

• it needs more resources and the grid on which it resides doesn't have more
• other applications need more resources and you want to free us some
• the grid where the application resides is being decommissioned or prepared for maintenance

Note that in the first two cases, you can also add more servers to the grid, up to the maximum supported number of servers (32 in version 1.2.3).

Note that the migration requires that the application is stopped during the migration process.

To migrate the application:

1. On your workstation or notebook, start ssh agent and provide a key that is valid on both the old grid and the new grid
2. Login to the new grid with ssh agent forwarding enabled (ssh -A newgrid.myhosting.com)
3. Migrate the application (app migrate oldgrid.myhosting.com myapp)
4. If the old application was running, it will be stopped prior to the migration; in that case, once the migration is complete, the application will be started on the new grid. Otherwise, you need to start it manually (app start myapp)
5. Once you are happy with the application running on the new grid, you can delete the application from the old grid (app destroy myapp executed on the old grid)

If the application needs different IP addresses or other settings to run properly on the new grid, make sure that you provide those new settings in the app migrate command. For example, to change the IP address and gateway during migration:

app migrate oldgrid.myhosting.com myapp primary_ip=209.100.101.12 gateway=209.100.101.1

You can change any configuration parameters during the migration, except volume sizes. See help on app migrate and app config for more details (look at the app entity in Command Line Shell or use the shell's built-in help: help app migrate).

Exporting and Importing Applications

Sometimes it is necessary to archive an application for backup purposes or to transfer the application to another grid that is not accessible.

To export an application

• Pick an export directory name where the exported application is to be stored. The export directory is accessible via ssh and sftp under the following URL: controllerhost:/vol/_impex/.
• If the application is running, stop the application app stop myapp
• Export the application app export myapp myapp. See app export command for details.
• Transfer the application to backup storage using sftp or scp - See Accessing the Grid for details.
  For example, to copy the application using secure copy, execute the following command:
  scp -r controllerhost:/vol/_impex/myapp . where controllerhost is the domain name of the controller.

To import an application

• Pick a unique name for the new application (e.g., myappnew)
• Transfer the application archive to the exchange directory on the Grid controller where the application is to be installed. scp -r ./myapp controllerhost:/vol/_impex.
• Import the application app export myappnew myapp. See app import command for details.

-- BeckyH - 02 Nov 2006