QWG Templates and Site Customization

Table of Contents

1. Template Hierarchies
2. Clusters and Template Hierarchies
   1. Cluster parameters
   2. Selecting OS and Kernel version
   3. RPM repositories
   4. Supporting several sites with one database
3. Hardware Templates
4. Template Compilation Tool

This page describes the template framework structure QWG templates is part of and how to integrate site custimizations into this framework.

QWG template framework has been designed to achieve the following goals :

• Provide generic templates for software installation and configuration, with local site parameters separated from provided templates.
• Preserve site customization across software upgrades (OS or middleware)
• Allow support of several sites sharing some configuration database, leveraging overall management load but keeping required flexibility.

Template Hierarchies

QWG LCG2 templates rely on a basic template structure based on template hierarchies. Each template hierarchy is dedicated to one specific aspect of the configuration, e.g. OS, LCG middleware, site specific parameters...

There is no imposed naming of template hierarchies, except for the clusters hierarchy which must contain cluster definition. clusters is the only hierarchy searched for machine profiles.

The suggested layout is :

• os : this hierarchy is used for OS related templates (e.g. RPMs associated with each feature group). Generally this hierarchy is made of one sub-hierarchy per OS version/architecture (e.g. sl308-386, sl440-x86_64). Most of the templates in these hierarchy are generated from OS distribution and should not be edited.
• grid : this hierarchy is used for templates related to EGEE/LCG middleware installation and configuration. Generally this hierarchy is made of one sub-hierarchy per middleware version (e.g. glite-3.0.0, glite-3.1). This hierarchy typically contains templates provided by QWG LCG. Most of these templates are configurable through variable definition and should require no edit.
• standard : this hierarchy is used for other kind of standard templates provided by some products, e.g. Quattor core templates, pan standard templates, Lemon templates... Generally this hierarchy contains one directory tree for each product. The templates in this hierarchy should not be edited.
• sites : this hierarchy is used for templates that are not standard (site specific templates or site customized version of standard templates) but are (potentially) common to several clusters. This hierarchy generally contains one sub-hierarchy per site. site concept is explained in more detail later but has no requirement to be linked to a physical location. Look at a site example.
• clusters : this hierarchy is used for cluster specific templates. There should be one sub-hierarchy per cluster. A cluster defines a group of machines sharing some common configuration. One specific of a cluster is that it must contain a directory profiles containing the machine profiles (e.g. object template used to define a machine configuration). It is valid for a cluster to have an empty profiles directory. Look at a cluster example.

Other pages describe in more details layout and customization of OS templates and gLite templates.

Clusters and Template Hierarchies

Each cluster is associated with one middleware version or sites by defining the appropriate include path used by pan compiler to locate templates. This include path is defined in the file cluster.build.properties at the top of each cluster hierarchy, (cfg/clusters/cluster-name).

This file must contain one line defining the property cluster.pan.includes as a list of space separated hierarchy list. The hierarchy is interpreted as a file pattern relative to the cfg directory (or whatever has been specified for cfg property in file quattor.build.xml). It must specify a directory that the template name (including it's relative position in the directory) must be appended to to locate the template file.

The include path is processed in the order specified. If a template exists in several hierarchies, the first one found according to the include path order is used.

Note : Legacy template names, as defined in the template statement at the beginning of the template, don't include the relative position of the template in its template hierarchy (called namespace). To include seach templates if they are spread to several sub-directories of the template hierarchy, you can specify to use all subdirectories instead of listing them explicitly, appending the pattern /**/* at the trail of the directory name. This entry must be added after the normal entry. With such legacy templates, if a template exists in several directories of a hierarchy, the inclusion order is unspecified.

Look at cluster.build.properties example. As reflected by this example, hierarchies of standard templates must be included after site specific templates (there may be several sites the cluster belongs to), in the following order : grid, os and standard.

Note : clusters/cluster-name hierarchy is implicitly added as the first entry in the include path. It should not be added explicitly to the cluster.build.properties file.

Cluster parameters

For every cluster, it is possible to customize its configuration in template pro_site_cluster_info.tpl. There must be one such template per cluster. Look at example provided for more information about the minimum set of variables to define.

One information required is the default root password for nodes in the cluster (it can also be customized on a per node basis, into the node profile). This must be the password hash as returned by command :

openssl passwd -1 my_preferred_password

Selecting OS and Kernel version

Refer to section about Configuring OS in documentation about OS template customizations.

RPM repositories

Each machine profile must contain the list of RPM repositories (directories where to download RPMs from) used in the profile. This is done by including at the end of the profile a cluster or site specific template, generally named repository/config.tpl. This must be done last in the machine profile and you should avoid doing this twice as this is a time consuming operation.

It is recommended to refer to this template through variable PKG_REPOSITORY_CONFIG and to define this variable in cluster specific pro_site_cluster_info.tpl. Using this method you should add at the end of each machine profile :

include { PKG_REPOSITORY_CONFIG };

Look at machine profile examples for more information.

Supporting several sites with one database

The recommended layout for Quattor templates provides a flexible support for multiple sites from a unique configuration database. According to the include path defined for each cluster, each cluster can share all standard templates part of its configuration information with other clusters.

Configuration common between several clusters is stored in a site hierarchy, stored under sites directory. As far as Quattor is concerned, a site doesn't have to match a geographical location but is an abstract entity corresponding to a set of shared configuration parameters. A cluster may belong to several sites corresponding to different set of common parameters. For example, a cluster may belong to 2 sites : mycity and gridsite. mycity will define parameters corresponding to a specific geographical locations (like network related parameters) that are common to all kind of clusters (grid machines, non grid servers, desktops...) at this geographical location. gridsite, on the other hand, will define parameters that are common to all grid machines, whatever geographical location they belong to.

Hardware Templates

Hardware configuration of machines is described as part of the machine profiles through a set of templates. There is one template for each kind of hardware subsystem (CPU, memory, nic...). They are located in standard/hardware. There is one subdirectory for each kind of hardware subsystem. There is also a legacy subdirectory with templates in the old format (non namespaced).

The recommandation is to create one template per machine that includes the appropriate templates to describe the machine hardware. The suggested location for these site specific templates are in hardware/machine in site directory. Look at examples for more information.

Note : if you have existing clusters that are using only the legacy, non namespaced, version of hardware template, you need to update cluster.build.properties in all your clusters and add standard/hardware/legacy after standard in cluster.pan.includes value.

Template Compilation Tool

The recommended method to process all the templates and build machine profiles is to use ant tool, a Java based equivalent of make, provided with SCDB (it can also be used without SCDB). ant brings the advantage of platform independance, allowing to do Quattor management tasks on any platform (Unix, Windows, MacOS).

Look at SCDB Usage documentation for more information on how to use this tool.