rPath Linux:group-appliance

From rPath Wiki

rPath Linux includes the superclass ApplianceGroupRecipe to provide the minimal basic operating system components and commonly used appliance tools to support an application. ApplianceGroupRecipe is packaged in group-appliance on one of the following labels:

• conary.rpath.com@rpl:1 for the appliance development community using components from rPath Linux, version 1
• conary.rpath.com@rpl:2 for the appliance development community using components from rPath Linux, version 2
• rap.rpath.com@rpath:linux-1 for rPath customers with a private rBuilder appliance and who are developing appliances based on version 1 of the rPath Appliance Platform
• rap.rpath.com@rpath:linux-2 for rPath customers with a private rBuilder appliance and who are developing appliances based on version 2 of the rPath Appliance Platform

Appliance developers can use ApplianceGroupRecipe from group-appliance with some introductory lines in the appliance group recipe. By using this superclass to automatically provide "just enough OS" for the appliance, the developers can focus their efforts on adding and modifying packages as needed to accommodate the application and complete the appliance. Also, when developers need to move the appliance to a different version of the underlying operating system, the change to the appliance group recipe is the label from which to load group-appliance.

Using the ApplianceGroupRecipe Superclass

The ApplianceGroupRecipe superclass automatically performs the common tasks required for an appliance. Each of the tasks that it performs can be individually customized as necessary, but typically there are few customizations required in the appliance group recipe.

Starting the Appliance Group Recipe

With group-appliance and ApplianceGroupRecipe, developers need only provide a single addPackages() method to specify the appliance-specific packages. The following is a template for an appliance group recipe that uses components from version 2 of the rPath Appliance Platform:

loadSuperClass('group-appliance=rap.rpath.com@rpath:linux-2')
class GroupExample(ApplianceGroupRecipe):
    name = 'group-example'
    version = '0.1'
    rapaLabel = 'products.rpath.com@rpath:rapa-3'
 
    def addPackages(r):
        r.add('example-application')
        r.add('rapa-customizations')
        r.replace('core-package-from-rpath')

By using ApplianceGroupRecipe and defining addPackages() as shown in the template, appliance developers can complete the appliance by focusing on the following tasks:

• Adding or replacing packages with group recipe classes to install and support the central application
• Modifying packages as needed from those provided by the rPath Appliance Platform to better accommodate the application or better fit the needs of the appliance (using derived packages and shadows).

Customizing the Appliance Group

After setting up the appliance group to use ApplianceGroupRecipe as previously described, developers can continue customizing the appliance group as appropriate.

Modifying the Search Path

Using certain elements of the recipe and default values in group-appliance, the ApplianceGroupRecipe superclass sets up a path to find the software used to build the appliance group. Each of these *SearchPath elements can be set as part of the recipe class variables when it is necessary to modify or extend the defaults. For each variable, set the value to a string or list of strings representing one or more Conary labels on which the packaged software resides. Add search path variable lines with other class variables such as name and version, and skip any which do not need to be modified from their default values.

rapaLabel

Set this variable equal to label for the rPath Appliance Platform Agent (rAPA). This must be specified as a label only. For example, in an appliance using the free version of rAPA 2.x, developers can use rapaLabel = 'raa.rpath.org@rpath:raa-2' in the recipe. When using rAPA components from multiple labels, use rPathAppliancePlatformAgentSearchPath instead.

initialSearchPath

This variable is set to the first place to look for software to add to the appliance. By default, this is set to the buildLabel set for the context in which the appliance is built, and only rarely it should it be added to a recipe with any other value. Additional labels to be searched alongside the buildLabel should be indicated with additionalSearchPath instead.

additionalSearchPath

Set this variable equal to a string or list of strings, each string representing an additional label or group on which to search for software. This value alongside the buildLabel provides all the locations to search for software for the appliance unless an overriding value is specified within the specific r.add() and r.replace() call. The following is an example showing the Python syntax used to assign the variable to a list of strings:

    additionalSearchPath = ['resources.example.com@corp:1', 'extras.example.com@corp:1']

rPathGroupSearchPath

This variable is set to the locations to search for the rPath Appliance Platform group. Its value should not need to be modified, and modifying it can result in an appliance group that fails to build or that can build only for some flavors.

rPathAppliancePlatformAgentSearchPath

This variable defaults to the contents of rapaLabel as the location for rAPA components. Modify the value of rPathAppliancePlatformAgentSearchPath to add labels or to set alternate labels for the appliance to obtain rAPA. Note that if this is set to something besides rapaLabel, any specified rapaLabel value is ignored. Note that this can include specific versions, like any other searchPath element.

finalSearchPath

This variable indicates additional labels on which to search for software which you want to include only if it is not already packaged as part of the rPath Appliance Platform. Use this when building a custom version of a package which you have requested to be added to the rPath Appliance Platform, allowing the appliance to automatically change to using the rPath Appliance Platform version if the request is approved.

kernelLabel

This variable can be set to a complete label and revision of a kernel to indicate that kernel specifically for the appliance instead of using Conary's automatic selection of the latest kernel appropriate for the build's flavor. Be sure the desired kernel version exists on the label specified and for the flavors to which it should apply. Be cautious of using this for images that are built for several different deployment scenarios, and use a conditional statement if necessary to indicate that kernelLabel is only applicable when using particular flavor specifications. For example, if you want the 2.6.19.7 kernel, but only when you are not building for a Xen DomU or VMware, you can use the following in the recipe (before the addPackages definition):

    if not Use.domU and not Use.vmware
        kernelLabel=conary.rpath.com@rpl:1/2.6.19.7-0.4-1

Modifying the kernel flavor

One of the benefits of group-appliance is that it has special built-in logic for including the appropriate kernel for given flavor of a group. In some rare cases this may need to be overridden. To do so, explicitly set kernelFlavor in the group recipe:

 
    if not Use.xen and not PackageFlags.kernel.pae:
        kernelFlavor = '!xen,!dom0,!domU,!kernel.pae,kernel.smp is: x86(i486,i586,i686)'

Note that rPath support should be informed of such scenarios, as it likely indicates an untested use case.

Additional Customizations

Each of the search path elements previously described is accessed with methods implemented in the ApplianceGroupRecipe superclass. The appliance group recipe may override any of those methods to modify their behavior. However, this is not generally recommended. One possible exception, though, is a need to modify the way that rAPA is added to the appliance: in such a case, developers can call addrPathAppliancePlatformAgent() in the appliance recipe.

Alternate Customization with addAppliancePlatform

Older versions of the ApplianceGroupRecipe superclass did not have the default setup() method and addPackages, and they required the appliance group recipe to implement a setup() method that called the addAppliancePlatform() method to include the common appliance contents in the appliance. Appliance groups already defining this setup() method will continue to work with this type of recipe.

With group-appliance and ApplianceGroupRecipe, the r.addAppliancePlatform() method includes the core operating system components. However, when implementing a custom setup() method instead of addPackages, the recipe must call the r.addAppliancePlatform() method to include the core appliance operating system components on the appliance. When addAppliancePlatform() is called, the build system creates an appropriate group-core for the appliance based on group-core=conary.rpath.com@rpl:1 and components from group-appliance-platform=conary.rpath.com@rpl:1.

The following is a template that has been used when implementing a custom setup() method and calling r.addAppliancePlatform(), showing using version 1 of the rPath Appliance Platform and rAPA 2:

loadSuperClass('group-appliance=rap.rpath.com@rpl:1')
class GroupExample(ApplianceGroupRecipe):
    name = 'group-example'
    version = '0.1'
 
    autoResolve = True
    depCheck = True
 
    def setup(r):
        r.addAppliancePlatform()
        r.add('group-raa', 'products.rpath.com@rpath:raa-2')
        # Remaining lines were truncated for this example

Appliance group recipes using this code will continue to work, but appliance developers should determine whether they can use the new addPackages method to simplify their recipes and overall development work.

Why group-appliance Exists

Before this superclass was created, appliance developers had to determine which flavors of group-core to include in an appliance group recipe, and they had to add other common appliance components in separate steps. In order to include the right flavor of group-core, a recipe would resemble the following recipe for an appliance using the free version of rPath Linux 1:

# This is the recipe without group-appliance
loadSuperClass('group-dist=conary.rpath.com@rpl:1')
class GroupExample(Dist):
    name = 'group-example'
    version = '0.1'
 
    autoResolve = True
    depCheck = True
 
    def setup(r):
        # This simplified version ignores vmware, xen domU, and
        # other flavor combinations
        if Arch.x86_64:
            groupFlavor = 'is:x86(i486,i586,i686) x86_64'
        else:
            groupFlavor = ''
        r.add('crontabs')
        r.add('vixie-cron')
        r.add('device-mapper:runtime')
        r.add('myapplication')
        r.add('raa')
        # add several other rPath Appliance Platform Agent packages
        r.add('raa-branding')
        r.replace('some-core-package')
        # Many remaining lines truncated for this example

Using group-appliance eliminates a lot of the extra code and redundant syntax that can clutter the recipe, and it automates building group-core in a way that is appropriate for the individual appliance.

Appliance group recipes using this code will continue to work, but appliance developers should determine whether they can use group-appliance to simplify their recipes and overall development work.