Difference between revisions of "Doc:Sdk 4.0/awdguide/appbundle"

m (12 revisions)
 
(9 intermediate revisions by one user not shown)
Line 1: Line 1:
 +
{{AwdDocHeader}}
 
==Application Bundle Format==
 
==Application Bundle Format==
  
Line 12: Line 13:
 
The appcfg.xml file describes the contents of the application bundle.  It is an xml V1.1 document with a simple layout.  As a simplification to standard XML, attributes and child tags are considered equivalent and the special attribute "value" is equivalent to child content.  The purpose is to allow the xml author to use whichever form is more convenient.  This concept is most easily understood by noting that all of the following are equivalent config files:
 
The appcfg.xml file describes the contents of the application bundle.  It is an xml V1.1 document with a simple layout.  As a simplification to standard XML, attributes and child tags are considered equivalent and the special attribute "value" is equivalent to child content.  The purpose is to allow the xml author to use whichever form is more convenient.  This concept is most easily understood by noting that all of the following are equivalent config files:
  
===="Classic" XML====
+
====Classic XML====
<pre>
+
<foo>
<foo>
+
  <bar>1</bar>
  <bar>1</bar>
+
</foo>
</foo>
+
</pre>
+
  
===="Compact" XML====
+
====Compact XML====
<pre>
+
<pre>
<foo bar="1" />
+
  <foo bar="1" />
</pre>
+
</pre>
  
 
====Partially compacted XML====
 
====Partially compacted XML====
<pre>
+
<pre>
<foo>
+
<foo>
  <bar value="1"></bar>
+
  <bar value="1"></bar>
</foo>
+
</foo>
</pre>
+
</pre>
  
 
===Example configuration file===
 
===Example configuration file===
Line 35: Line 34:
 
The following is a typical appcfg.xml configuration file.  This file is used in the SAFplus Platform virtualIp example provided with your SAFplus Platform source distribution:
 
The following is a typical appcfg.xml configuration file.  This file is used in the SAFplus Platform virtualIp example provided with your SAFplus Platform source distribution:
  
<pre>
+
<virtualIp ver="1.4.0.0">
<virtualIp ver="1.4.0.0">
+
<programNames prog0="vip" />
<programNames prog0="vip" />
+
<redundancyModel value="3+1" />
<redundancyModel value="3+1" />
+
<totalNodes value="4" />
<totalNodes value="4" />
+
<modifiers>
<modifiers>
+
  <failBack value="false" />
  <failBack value="false" />
+
  <autoRepair value="true" />
  <autoRepair value="true" />
+
  <restartsBeforeFailure value='0' />
  <restartsBeforeFailure value='0' />
+
  <activeStandbyRatio value='50' />
  <activeStandbyRatio value='50' />
+
</modifiers>
</modifiers>
+
<messages>
<messages>
+
  <newDeployment>Virtual IP application deployed.  Please edit the work assignment (SAF SI) to customize your virtual IP address and interface before starting it.</newDeployment>
  <newDeployment>Virtual IP application deployed.  Please edit the work assignment (SAF SI) to customize your virtual IP address and interface before starting it.</newDeployment>
+
</messages>
</messages>
+
<work>
<work>
+
  <firstIp VirtualIpAddress="192.168.1.250" VirtualNetMask="255.255.255.0" VirtualDevice="eth0:10" />
  <firstIp VirtualIpAddress="192.168.1.250" VirtualNetMask="255.255.255.0" VirtualDevice="eth0:10" />
+
</work>
</work>
+
</virtualIp>
</virtualIp>
+
</pre>
+
  
 
The tags are described as follows:
 
The tags are described as follows:
  
===Root Tag===
 
  
 +
===Root Tag===
 
The root tag (in this case "virtualIp") is the name of the application (SAF Service Group).   
 
The root tag (in this case "virtualIp") is the name of the application (SAF Service Group).   
 +
  
 
====Attribute: ver====
 
====Attribute: ver====
  It has a single attribute "ver" that specifies the version of the software in a 4 dotted digit format.
+
It has a single attribute "ver" that specifies the version of the software in a 4 dotted digit format.
  
===ProgramNames===
 
  
 +
===ProgramNames===
 
ProgramNames specifies the names of every SAF component to be run in the application (SAF Service Group).  A single SAF Service Unit will be created on each node that this Service Group is deployed onto, and this SU will contain 1 component for every specified attribute to this tag.   
 
ProgramNames specifies the names of every SAF component to be run in the application (SAF Service Group).  A single SAF Service Unit will be created on each node that this Service Group is deployed onto, and this SU will contain 1 component for every specified attribute to this tag.   
  
====Attribute: progN====
 
  
 +
====Attribute: progN====
 
This tag takes any number of attributes, labelled prog0...progN.  Each attribute specifies the name of a Component to be created, and also the name of a binary located in "deploy/bin" that the component will run.   
 
This tag takes any number of attributes, labelled prog0...progN.  Each attribute specifies the name of a Component to be created, and also the name of a binary located in "deploy/bin" that the component will run.   
  
 
Example:
 
Example:
 
  <programNames prog0="vip" prog1='myProg' />
 
  <programNames prog0="vip" prog1='myProg' />
 +
  
 
===RedundancyModel===
 
===RedundancyModel===
 
 
Specify what type of redundancy this Service Group requires
 
Specify what type of redundancy this Service Group requires
  
 
====Attribute: value====
 
====Attribute: value====
 
 
This specifies the redundancy model.  Possible values are:
 
This specifies the redundancy model.  Possible values are:
 
* "2N": 1 Active/1 standby redundancy
 
* "2N": 1 Active/1 standby redundancy
Line 87: Line 84:
  
 
Example:
 
Example:
<redundancyModel value="3+1" />
+
<redundancyModel value="3+1" />
 +
 
  
 
===totalNodes===
 
===totalNodes===
 
 
Recommend the optimal number of nodes to run this application on.
 
Recommend the optimal number of nodes to run this application on.
  
 
====Attribute: value====
 
====Attribute: value====
 
 
A number specifying the number of nodes
 
A number specifying the number of nodes
  
 
Example:
 
Example:
<totalNodes value="4" />
+
<totalNodes value="4" />
  
  
 
===modifiers===
 
===modifiers===
 
+
To override the default configuration for any Service Group configuration parameter, specify the parameter and value as a child tag of this tag.  The possible child tags are standard SAF and are also documented in the AWD GUI's deployment page under "Advanced Configuration", or in the SAF AMF, SAFplus Platform SDK or IDE documentation.
To override the default configuration for any Service Group configuration parameter, specify the parameter and value as a child tag of this tag.  The possible child tags are standard SAF and documented in the AWD GUI's deployment page under "Advanced Configuration", or in the SAF AMF, SAFplus Platform SDK or IDE documentation.
+
  
 
Example:
 
Example:
<pre>
 
<modifiers>
 
  <failBack value="false" />
 
  <autoRepair value="true" />
 
  <restartsBeforeFailure value='0' />
 
  <activeStandbyRatio value='50' />
 
</modifiers>
 
</pre>
 
  
===messages===
+
<modifiers>
 +
  <failBack value="false" />
 +
  <autoRepair value="true" />
 +
  <restartsBeforeFailure value='0' />
 +
  <activeStandbyRatio value='50' />
 +
</modifiers>
  
 +
 +
====failback====
 +
Should work be automatically moved back to the original location after a failure?
 +
 +
====autoRepair====
 +
After a failure, should a node be put directly back into service, or should an adminstrative reset be required.
 +
 +
====instantiateDuration (Instantiation delay)====
 +
How long to wait after system startup before starting this application.
 +
 +
====numPrefActiveSUs (Preferred number of active nodes)====
 +
Active nodes are executing your application.
 +
 +
====numPrefStandbySUs (Preferred number of standby nodes)====
 +
These nodes act as redundant backups for the active nodes.
 +
 +
====numPrefIdleSUs (Preferred number of idle nodes)====
 +
Idle nodes have the application running but no work assignments.  For example, if this number is 0 the application will not be started on any nodes until it is needed.  If 1 it will be started on 1 additional node (assuming that the app is deployed to enough nodes).
 +
 +
====maxActiveSIsPerSU (Maximum active work)====
 +
Maximum active work assignments on one program.
 +
 +
====maxStandbySIsPerSU (Maximum standby work)====
 +
Maximum standby work assignments on one program.
 +
 +
====compRestartDuration (Process validation period)====
 +
If a process fails X times within this duration the failure is escalated.  X is the 'Maximum process failure count' below.
 +
 +
====compRestartCountMax (Maximum process failure count)====
 +
How many times to restart a failed component before giving up and escalating to all processes on this node in this deployment.
 +
 +
====suRestartDuration (Service Unit restart duration)====
 +
If all processes in this deployment on one node take longer than this time to start up, the deployment is considered failed.
 +
 +
====suRestartCountMax (Maximum service unit failure count)====
 +
How many times to restart all the processes in this deployment before giving up and moving work to another node.
 +
 +
====isCollocationAllowed (Collocation)====
 +
Allow multiple instances to run on the same node.  WARNING: doing so may mean that work is assigned active and standby on the same node, which means you will not have physical redundancy!
 +
 +
====alpha (Redundancy degradation ratio)====
 +
Percent of active nodes vs standby nodes when the preferred configuration can not be met
 +
 +
====autoAdjust (Automatic work adjustment)====
 +
Automatically move work assignments between blades to match as closely as possible the configured work->node preferences.
 +
 +
====autoAdjustProbation (Work adjustment interval)====
 +
How long between checks to see if work adjustments need to be made
 +
 +
====reductionProcedure (Automatic active assignment )====
 +
As nodes are removed, standby work assignments are automatically removed to make room for active work assignments
 +
 +
 +
===messages===
 
The messages section allows you to provide a message to the user during certain actions.
 
The messages section allows you to provide a message to the user during certain actions.
  
====newDeployment====
 
  
 +
====newDeployment====
 
The new deployment tag specifies the message to print after a successful deployment of this application.
 
The new deployment tag specifies the message to print after a successful deployment of this application.
  
 
Example:
 
Example:
<pre>
+
<pre>
<messages>
+
  <messages>
<newdeployment>This application is deployed onto the selected nodes.</newdeployment>
+
  <newdeployment>This application is deployed onto the selected nodes.</newdeployment>
</messages>
+
  </messages>
</pre>
+
</pre>
 +
 
  
 
===work===
 
===work===
Line 134: Line 181:
  
 
Example:
 
Example:
<pre>
+
 
<work>
+
<work>
  <firstIp VirtualIpAddress="192.168.1.250" VirtualNetMask="255.255.255.0" VirtualDevice="eth0:10" />
+
  <firstIp VirtualIpAddress="192.168.1.250" VirtualNetMask="255.255.255.0" VirtualDevice="eth0:10" />
</work>
+
</work>
</pre>
+

Latest revision as of 19:06, 24 October 2011

Contents

[edit] Application Bundle Format

An application bundle is a gzipped tar file (.tgz, open via the "tar xvfz <file>" command) that contains at a minimum the following layout:

appcfg.xml
deploy (a directory)
  bin  (a directory)
    <application binary files>
  etc
    <application configuration files>

The appcfg.xml file describes the contents of the application bundle. It is an xml V1.1 document with a simple layout. As a simplification to standard XML, attributes and child tags are considered equivalent and the special attribute "value" is equivalent to child content. The purpose is to allow the xml author to use whichever form is more convenient. This concept is most easily understood by noting that all of the following are equivalent config files:

[edit] Classic XML

<foo>
  <bar>1</bar>
</foo>

[edit] Compact XML

   <foo bar="1" />
 

[edit] Partially compacted XML

 <foo>
   <bar value="1"></bar>
 </foo>
 

[edit] Example configuration file

The following is a typical appcfg.xml configuration file. This file is used in the SAFplus Platform virtualIp example provided with your SAFplus Platform source distribution:

<virtualIp ver="1.4.0.0">
<programNames prog0="vip" />
<redundancyModel value="3+1" />
<totalNodes value="4" />
<modifiers>
  <failBack value="false" />
  <autoRepair value="true" />
  <restartsBeforeFailure value='0' />
  <activeStandbyRatio value='50' />
</modifiers>
<messages>
  <newDeployment>Virtual IP application deployed.  Please edit the work assignment (SAF SI) to customize your virtual IP address and interface before starting it.</newDeployment>
</messages>
<work>
  <firstIp VirtualIpAddress="192.168.1.250" VirtualNetMask="255.255.255.0" VirtualDevice="eth0:10" />
</work>
</virtualIp>

The tags are described as follows:


[edit] Root Tag

The root tag (in this case "virtualIp") is the name of the application (SAF Service Group).


[edit] Attribute: ver

It has a single attribute "ver" that specifies the version of the software in a 4 dotted digit format.


[edit] ProgramNames

ProgramNames specifies the names of every SAF component to be run in the application (SAF Service Group). A single SAF Service Unit will be created on each node that this Service Group is deployed onto, and this SU will contain 1 component for every specified attribute to this tag.


[edit] Attribute: progN

This tag takes any number of attributes, labelled prog0...progN. Each attribute specifies the name of a Component to be created, and also the name of a binary located in "deploy/bin" that the component will run.

Example:

<programNames prog0="vip" prog1='myProg' />


[edit] RedundancyModel

Specify what type of redundancy this Service Group requires

[edit] Attribute: value

This specifies the redundancy model. Possible values are:

  • "2N": 1 Active/1 standby redundancy
  • "N+M": N Active/N standby redundancy
  • "custom": The application will explicitly assign redundancy

Example:

<redundancyModel value="3+1" />


[edit] totalNodes

Recommend the optimal number of nodes to run this application on.

[edit] Attribute: value

A number specifying the number of nodes

Example:

<totalNodes value="4" />


[edit] modifiers

To override the default configuration for any Service Group configuration parameter, specify the parameter and value as a child tag of this tag. The possible child tags are standard SAF and are also documented in the AWD GUI's deployment page under "Advanced Configuration", or in the SAF AMF, SAFplus Platform SDK or IDE documentation.

Example:

<modifiers>
  <failBack value="false" />
  <autoRepair value="true" />
  <restartsBeforeFailure value='0' />
  <activeStandbyRatio value='50' />
</modifiers>


[edit] failback

Should work be automatically moved back to the original location after a failure?

[edit] autoRepair

After a failure, should a node be put directly back into service, or should an adminstrative reset be required.

[edit] instantiateDuration (Instantiation delay)

How long to wait after system startup before starting this application.

[edit] numPrefActiveSUs (Preferred number of active nodes)

Active nodes are executing your application.

[edit] numPrefStandbySUs (Preferred number of standby nodes)

These nodes act as redundant backups for the active nodes.

[edit] numPrefIdleSUs (Preferred number of idle nodes)

Idle nodes have the application running but no work assignments. For example, if this number is 0 the application will not be started on any nodes until it is needed. If 1 it will be started on 1 additional node (assuming that the app is deployed to enough nodes).

[edit] maxActiveSIsPerSU (Maximum active work)

Maximum active work assignments on one program.

[edit] maxStandbySIsPerSU (Maximum standby work)

Maximum standby work assignments on one program.

[edit] compRestartDuration (Process validation period)

If a process fails X times within this duration the failure is escalated. X is the 'Maximum process failure count' below.

[edit] compRestartCountMax (Maximum process failure count)

How many times to restart a failed component before giving up and escalating to all processes on this node in this deployment.

[edit] suRestartDuration (Service Unit restart duration)

If all processes in this deployment on one node take longer than this time to start up, the deployment is considered failed.

[edit] suRestartCountMax (Maximum service unit failure count)

How many times to restart all the processes in this deployment before giving up and moving work to another node.

[edit] isCollocationAllowed (Collocation)

Allow multiple instances to run on the same node. WARNING: doing so may mean that work is assigned active and standby on the same node, which means you will not have physical redundancy!

[edit] alpha (Redundancy degradation ratio)

Percent of active nodes vs standby nodes when the preferred configuration can not be met

[edit] autoAdjust (Automatic work adjustment)

Automatically move work assignments between blades to match as closely as possible the configured work->node preferences.

[edit] autoAdjustProbation (Work adjustment interval)

How long between checks to see if work adjustments need to be made

[edit] reductionProcedure (Automatic active assignment )

As nodes are removed, standby work assignments are automatically removed to make room for active work assignments


[edit] messages

The messages section allows you to provide a message to the user during certain actions.


[edit] newDeployment

The new deployment tag specifies the message to print after a successful deployment of this application.

Example:

   <messages>
   <newdeployment>This application is deployed onto the selected nodes.</newdeployment>
   </messages>
 


[edit] work

The work tag is used to specify the work assignments (SAF Service Instance and Component Service Instances) for this application. Each item of work is defined by a child tag, and the tag name will become the name of the SAF Service Instance. Attributes become the name/value pairs in each CSI. This specification is simpler than the full SAF definition and so covers a subset of the full SAF expressibility. In particular, every component defined in the "ProgramNames" tag will have a CSI created for it, and each CSI will contain every name/value pair.

Example:

<work>
  <firstIp VirtualIpAddress="192.168.1.250" VirtualNetMask="255.255.255.0" VirtualDevice="eth0:10" />
</work>