wiki:Doc/TemplateCustom

Version 26 (modified by /C=FR/O=CNRS/OU=UMR8607/CN=Michel Jouvin/emailAddress=jouvin@…, 17 years ago) (diff)

--

QWG Templates and Site Customization

TracNav

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 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. As a general rule, you need to define the following properties for each cluster (value mentionned are just examples) : 

#
# basic site information
#
"/system/cluster/name" = "LCG 2.7.0";
"/system/cluster/type" = "batch";
"/system/state" = "production";
"/system/siterelease" = "SL 3.05";
"/system/rootmail" = "grid.support@lal.in2p3.fr";

You can also define variable FILESYSTEM_CONFIG_SITE as an alternative template name containing a filesystem layout for the cluster (or node if this is in a machine profile). For example : 

FILESYSTEM_CONFIG_SITE = "pro_lcg2_system_filesystems";

pro_site_cluster_info.tpl is often used to define the default root password in a cluster. This can be done with the following PAN instructions : 

#
# set root password on machines
#
include pro_software_component_accounts;
"/software/components/accounts/rootpwd" = default("$1$57qRuCXe$NPngMkg4BrPBf5hfJzJh21");
"/software/components/accounts/shadowpwd" = true;

The encrypted password value must be provided. It can be obtained with the following command : 

openssl passwd -1 my_preferred_password

Selecting OS and Kernel version

Refer to page on Configuring OS.

RPM repositories

Each machine profile must contain the list of RPM repositories used by the profile (cluster). This is not done in any standard template. This should be done last in the machine profile and you should avoid doing this twice as this is a time consuming operation.

This is generally done by one template and, by convention, this template is located in repository directory of cluster hierarchy. Example of such templates are provided as part of QWG templates. After creating the repository list, the template must call the following 2 functions to check the presence of all RPMs required in one of the repository and purge the profile of all the unneeded information : 

#
# Standard stuff: resolve repository and purge not used entries
#
"/software/packages" = resolve_pkg_rep(value("/software/repositories"));
"/software/repositories" = purge_rep_list(value("/software/packages"));

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. Very often, a cluster will belong to several sites corresponding to different set of common parameters. For example, in the above example, the cluster belongs to 2 sites : lal and grif. lal defines 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...). grif, on the other hand, defines 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 templates/trunk/sites/example/hardware examples for more information.

Note : if you have existing clusters that where using only the legacy, non namespaced, version of hardware template, you need to update cluster.build.properties in all your clusters and add sites/mysite before sites/mysite/**/* 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.