How to use and customize
Example 42 Puppet Modules
Lab42's proposal of recipes and a coherent infrastructure is a work in progress.
Support for different operating systems and different Puppet versions is shown in the status page.
Use, if you want, these modules, in parts or as a whole, as a starting point to build your Puppet modules in a test environment.
Customization of the modules is just necessary, read below our hints on how to grasp in few time the basic logic behind Example42 approach.
Step 1 - Download and "install"
Example42 is divided in two different repos:
- Puppet modules , a set of modules to manage different appications (basically the contents of a directory like /etc/puppet/modules );
- Puppet Infrastructure, some sample Puppet infrastrucutres layouts (the content of /etc/puppet/manifests).
To setup a PuppetMaster on a vanilla RedHat / Centos 5 system you have to first install the Epel repository and then the Puppet packages downloaded from there:
rpm -Uvh http://download.fedora.redhat.com/pub/epel/5/i386/epel-release-5-3.noarch.rpm
yum install puppet puppet-server
yum install git
git clone git://www.example42.com/example42modules /etc/puppet/modules
git clone git://www.example42.com/example42infrastructures /etc/puppet/manifests
On Debian/Ubuntu there's no need to add an extra repo, so you just can:
apt-get install puppet puppet-server
apt-get install git
git clone git://www.example42.com/example42modules /etc/puppet/modules
git clone git://www.example42.com/example42infrastructures /etc/puppet/manifests
Step 2 - Basic setup
Once downloaded the "source" you need to decide the basic infrastructure layout to start from and then adapt all the references to Example42 to your own domains and hostnames.
One of the first choices to make is between the use of an external node tool (such as the Foreman or Puppet Dashboard) to define node names, variables, and included classes or the use of plain text-based Puppet manifests.
In the first case you'll need to modify /etc/puppet/puppet.conf (look here for details) and install the external tool.
In the second case, the Example42 Puppet Infrastructure samples downloaded in /etc/puppet/manifests can be a good starting point.
First of all you have to decide what's the basic layout, that is imported in /etc/puppet/manifests/site.pp
Then you will probably change all the references to the nodes' names and the variables defined in the nodes' inheritance tree.
Look, for example, in example42_small/nodes.pp (if you start from the "small site" template) or in example42_medium/nodes/* and example42_medium/infrastructures/* (if you start from the "medium site" template).
Mass renaming of files' contents can be done with a script like:
OLDPROJECT="example42"
NEWPROJECT="mycompany"
cd /etc/puppet/manifests/example42_medium
for a in $( grep -R $OLDPROJECT . | cut -d ":" -f 1 | uniq ) ; do
echo $a
sed -i "s/$OLDPROJECT/$NEWPROJECT/g" $a
done
Step 3 - Customize
Now you can start to customize your manifests in order to reflect your infrastructure logic.
First of all note that you can define the logic of your infrastructure, independently from the modules you use. You can completely change and adapt the suggested ones accordinging to your needs (or, again, you can use an external node tool (such as The Foreman or Puppet Dashboard) and define your nodes, the classes they include and the relevant variables in the external tool).
The modules, more or less application oriented, are where real configurations are defined.
Each of these modules is organized according to Reductive Labs suggested Module organization:
In module_name/manifests/init.pp there is the starting manifest.
Here you find a class (with the same name of the module) and possible subclasses for specific functions of the same applications (ex: cobbler and cobbler::full).
The primary class (ex: samba) does not overwrite configuration files but only define the general types, whose properties can be modified by subclasses that inherit the main one (ex: samba::pcd).
The infrastructure manifests needs some explanation:
- example42_small is good for a site with few nodes (1-20) where you list for each node the variables and the classes they include.
- example42_medium is more structured, in order to adapt to much larger and heterogenous installations. Read below to understand its logic.
Understaning example42_medium infrastructure logic
example42_medium/site.pp is the first manifest parsed by Puppet when you use example42_medium, this just sets up some site-wide default settings and imports other manifests:
In the subdirectory infrastructures/ there are different examples of different layouts of IT infrastructures. Here different zones are defined (it's good idea to consider a zone as a dedicated IP network or as a specific functional area (ex: dmz1, dmz2, frontend, backend, intranet, devel etc)) in order to distinguish nodes according to different zones. For more info about the logic of zones and roles give a look to Infrastructure Design Guidelines. In this directory you find the file basenode.pp where are defined to variables for the basenode (inheritend by all the other nodes):
and various other files, defining examples or different layouts. Choose and adapt what you need and remove the others.
These files just define zone nodes that will be inherited by your real host nodes.
In the subdirectory nodes/ you can define your specific nodes settings. Here you MUST change the node names according to your puppet client hostnames. A single host-node can inherit existing zone-nodes with the possibility of overriding variables defined at more general levels. You CAN decide if it's better for your case to include different modules directly at node level, or include more general roles, that can be used by more nodes. At node level you can just include a specific role. You can decide to split your nodes definition in different files according to your own logic and your control delegation needs.
In the subdirectory roles/ you define the various roles used by the nodes (for example "webserver", "fileserver", "mta" or whatever).
It's a good idea to define the variable $my_role with the name of the role and $my_zone with the name of the zone (so you can differentiate configurations according to the node's role or zone).
In the subdirectory baselines/ are grouped some general classes that include other classes. There are default baselines that are applied to all your hosts. For example baselines/general.pp :
Note that according to this design a node inherits a zone and includes a role:
- Only ONE inheritance tree for nodes: general node - [zone/network/environment] - [ subzone ] - node
- Each node may include a SINGLE specific role, where you define what modules to use
- To avoid variables scoping mess, always define variables before including classes and possibly do not define variables (except $my_role) in roles or baselines. For this reason, zone-node should not include any class, but just define variables (that can be inherited or overwritten in the nodes inheritance's tree).
Now, how to organize your own infrastructure actually depends only on its complexity and specificity.
What should be respected is the use of few specific custom variables:
- $my_zone defines the zone (environment) inherited by the host node (devel, test, prod..),
- $my_role defines the role of the host node (webserver, proxy, mail... )
Other variables might be requested by specific modules, for example:
- $puppet_server defines the servername of the puppet master (used in the puppet module),
- $ntp_server defines the servername of the NTP server (used in the ntp module),
- $syslog_servers defines the servername of the syslog server(s) (may be an array) (used in the syslog module),
You can decide to apply and use these variables according to the modules you decide to use.
A fast way to see what module uses what variable (for example "$syslog_server" is a command like this at the root of your modules directory
grep -R syslog_server *
use similar searches to reconstruct the logic of the Example 42 Puppet Infrastructures and realize how theris components are assembled.