en-US/Books/PuppetWorkshop/Course-Appendix.xml | 166 ++++
en-US/Books/PuppetWorkshop/Course.xml | 950 ++++++++++++++++++++++++-
2 files changed, 1079 insertions(+), 37 deletions(-)
New commits:
commit c997f43d392726273d2247382d039c6c6202dfa9
Author: Jeroen van Meeuwen (Fedora Unity) <kanarip(a)fedoraunity.org>
Date: Sun Oct 5 16:34:09 2008 +0200
Updates to the puppet workshop
diff --git a/en-US/Books/PuppetWorkshop/Course-Appendix.xml
b/en-US/Books/PuppetWorkshop/Course-Appendix.xml
index 5b02ee8..e87a9bb 100644
--- a/en-US/Books/PuppetWorkshop/Course-Appendix.xml
+++ b/en-US/Books/PuppetWorkshop/Course-Appendix.xml
@@ -4,10 +4,170 @@
<part id="PuppetWorkshop-Appendices">
<title>Appendices</title>
- <appendix id="PuppetWorkshop-AppendixA">
- <title>Puppet Workshop AppendixA</title>
+ <appendix id="PuppetWorkshop-Appendix-Terminology">
+ <title>Puppet Terminology</title>
<para>
- paragraph
+ <itemizedlist>
+ <listitem>
+ <formalpara>
+ <title>class</title>
+ <para>
+ A class is a collection of resources applied to a node with a
single include statement. It groups together a comprehensible set of resources. A class
<emphasis>ypclient</emphasis> would manage the
<code>File["/etc/nsswitch.conf"]</code>,
<code>File["/etc/yp.conf"]</code>,
<code>Package["ypbind"]</code>, and
<code>Service["ypbind"]</code> resources.
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>fact</title>
+ <para>
+ A client-side generated aspect of the node the puppet client
runs on. Example facts are the amount of available memory, the hostname, the fully
qualified domain name, the operating system (version).
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>manifest</title>
+ <para>
+ The collection of classes, modules and resources that the
<xref linkend="PuppetWorkshop-Appendix-Terminology-puppetmaster" /> uses
to distribute the appropriate configuration to a <xref
linkend="PuppetWorkshop-Appendix-Terminology-puppet" />.
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>module</title>
+ <para>
+ module
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>node</title>
+ <para>
+ The client, a node, is an operating system instance running
the puppet client application. This can be a regular operating system running directly on
top of actual hardware, a virtual guest as well as a virtual host.
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara
id="PuppetWorkshop-Appendix-Terminology-puppet">
+ <title>puppet</title>
+ <para>
+ The client, a node, runs the
<application>puppetd</application> daemon or service, and is referred to as
the <emphasis>puppet</emphasis>
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara
id="PuppetWorkshop-Appendix-Terminology-puppetmaster">
+ <title>puppetmaster</title>
+ <para>
+ The puppetmaster is the node that runs the server-side
application to a puppet setup.
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>resource</title>
+ <para>
+ A resource is an instantiated <xref
linkend="PuppetWorkshop-Appendix-Terminology-type" />
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>system resource</title>
+ <para>
+ A system resource is a resource available on the node whether
it is managed by puppet or not. Unlike in other cases, this term does not as much to
system hardware resources such as the CPU or memory available to the operating system,
because that.
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara
id="PuppetWorkshop-Appendix-Terminology-type">
+ <title>type</title>
+ <para>
+ definition
+ </para>
+ </formalpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </appendix>
+ <appendix
id="PuppetWorkshop-Appendix-ExampleSSLFrontendReverseProxyLoadBalancerConfiguration">
+ <title>Example SSL Frontend Reverse Proxy Load Balancer
Configuration</title>
+ <para>
+<screen>
+<ifModule !mod_proxy.c>
+ LoadModule proxy_module modules/mod_proxy.so
+</IfModule>
+
+<IfModule !mod_proxy_http.c>
+ LoadModule proxy_http_module modules/mod_proxy_http.so
+</IfModule>
+
+<IfModule !mod_proxy_balancer.c>
+ LoadModule proxy_balancer_module modules/mod_proxy_balancer.so
+</IfModule>
+
+<IfModule !mod_headers.c>
+ LoadModule headers_module modules/mod_headers.so
+</IfModule>
+
+<IfModule !mod_ssl.c>
+ LoadModule ssl_module modules/mod_ssl.so
+</IfModule>
+
+<IfModule !mod_authz_host.c>
+ LoadModule authz_host_module modules/mod_authz_host.so
+</IfModule>
+
+<IfModule !mod_log_config.c>
+ LoadModule log_config_module modules/mod_log_config.so
+</IfModule>
+
+<Directory />
+ Options FollowSymLinks
+ AllowOverride None
+ Order deny,allow
+ Deny from all
+</Directory>
+
+<Proxy balancer://master.puppetmanaged.org>
+ BalancerMember
http://127.0.0.1:8141 keepalive=on retry=30
+</Proxy>
+
+<VirtualHost *:8140>
+ ServerName
master.puppetmanaged.org
+ SSLEngine on
+ SSLCipherSuite SSLv2:-LOW:-EXPORT:RC4+RSA
+ SSLCertificateFile /var/lib/puppet/ssl/certs/master.puppetmanaged.org.pem
+ SSLCertificateKeyFile
/var/lib/puppet/ssl/private_keys/master.puppetmanaged.org.pem
+ SSLCertificateChainFile /var/lib/puppet/ssl/ca/ca_crt.pem
+ SSLCACertificateFile /var/lib/puppet/ssl/ca/ca_crt.pem
+ SSLVerifyClient optional
+ SSLVerifyDepth 1
+ SSLOptions +StdEnvVars
+
+ # The following client headers allow the same configuration to work with Pound.
+ RequestHeader set X-SSL-Subject %{SSL_CLIENT_S_DN}e
+ RequestHeader set X-Client-DN %{SSL_CLIENT_S_DN}e
+ RequestHeader set X-Client-Verify %{SSL_CLIENT_VERIFY}e
+
+ <Location />
+ SetHandler balancer-manager
+ Order allow,deny
+ Allow from all
+ </Location>
+
+ ProxyPass / balancer://master.puppetmanaged.org:8140/ timeout=180
+ ProxyPassReverse / balancer://master.puppetmanaged.org:8140/
+ ProxyPreserveHost on
+ SetEnv force-proxy-request-1.0 1
+ SetEnv proxy-nokeepalive 1
+
+ ErrorLog logs/master.puppetmanaged.org-balancer-error_log
+ CustomLog logs/master.puppetmanaged.org-balancer-access_log combined
+ CustomLog logs/master.puppetmanaged.org-balancer-ssl_request_log "%t %h
%{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"
+</VirtualHost>
+</screen>
</para>
</appendix>
<xi:include href="Revision_History.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
diff --git a/en-US/Books/PuppetWorkshop/Course.xml
b/en-US/Books/PuppetWorkshop/Course.xml
index 794ad47..30b45df 100644
--- a/en-US/Books/PuppetWorkshop/Course.xml
+++ b/en-US/Books/PuppetWorkshop/Course.xml
@@ -11,94 +11,976 @@
<chapter id="PuppetWorkshop-Introduction">
<title>Introduction</title>
<para>
- Welcome to the Puppet Workshop (or Configuration Management workshop).
+ Welcome to the Puppet Workshop (or Configuration Management workshop).
Today's workshop is comprised of the following topics:
+ </para>
+ <para>
+ <segmentedlist>
+ <segtitle>Topic</segtitle>
+ <seglistitem>
+ <seg>Introduction to Configuration Management</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>Introduction to Puppet</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>Puppet Terminology</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>How Puppet Works</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>Puppet Features</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>Troubleshooting Puppet</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>Setting up Puppet</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>How to use Puppet</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>Other Things To Do With Puppet</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>Best Practices</seg>
+ </seglistitem>
+ </segmentedlist>
</para>
</chapter>
- <chapter id="PuppetWorkshop-ConfigurationManagement">
- <title>Configuration Management</title>
- <section
id="PuppetWorkshop-ConfigurationManagement-WhatIsConfigurationManagement">
+ <chapter
id="PuppetWorkshop-IntroductionToConfigurationManagement">
+ <title>Introduction to Configuration Management</title>
+
+ <section
id="PuppetWorkshop-IntroductionToConfigurationManagement-WhatIsConfigurationManagement">
<title>What is Configuration Management?</title>
<para>
- With configuration management, generally speaking, it's about
managing the configuration of an organizational resource in order to have it be in a state
in which it can perform the operations required by, and possibly critical to, the
organization.
+ Within virtually every organization, there's probably a number of
systems running Linux, Solaris, Mac OS X or HP-UX. All these machines need to be
configured to be able to function properly. Some will need special drivers, and all of
them will need correct DNS settings, certain packages installed and certain other packages
removed. Most probably, the more systems, the more these diverge in the configuration they
need, and potentially diverge in the way this configuration needs to be applied to a given
operating system or operating system version.
</para>
<para>
- In this workshop though, we are not going to explore configuration
management of a coffee machine. Instead we look at the computers in a network running any
platform but the one from a prominent proprietary North America-based vendor. We are
talking automation and further enhancement of Computer Systems Administration.
+ More specifically, an organization may have a couple of webservers,
fileservers, a DNS and a DHCP server, a number of desktop PCs, and a number of laptops.
The laptops may need slightly different system configuration (no LDAP authentication, and
with a VPN client installed, for example), and the desktop PCs may need different
applications installed then the servers, and so forth. Yet, between, say, a hundred
desktop PCs, you would want the configuration to be as similar as possible. You may want
to diverge between a software developer's desktop PC and a desktop PC in Human
Resources, but in essence these are desktop profiles diverging on the application level,
applied upon a stable system configuration which remains the same, or similar at least.
</para>
<para>
- When managing the operating system and software running on
mainframes, servers, desktop PCs and laptops
+ By the time the organization grows, replaces the hardware, upgrades
to another version of the operating system, or applies changes, the challenge to making
everything work yet maintain a similar configuration between all nodes becomes bigger.
While every attempt made to control the situation can be called a form of configuration
management, the solution without a configuration management framework is often comprised
of:
</para>
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>
+ a number of scripts (with or without revision control),
to move around files, install packages, perform daily check-ups,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ NFS mounts with programs pre-installed, so that nodes can
mount these NFS shares and the software needs to be provided once, in one location, for
all to share,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ file server shares with pre-compiled drivers, or driver
sources being compiled on the nodes by scripts running on the nodes,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ terminal servers or desktop servers like with FreeNX, so
that configuration concentrates on a smaller number of boxes
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ <para>
+ This means that work-arounds for actual (user) problems maybe require
an additional if-then-else in one or the other script, and updates to programs installed
require manual compilation and installation. The success rate of these solutions never
reaches 100%, and as it turns out the longer such solution implemented runs, the more
exotic problems become and the more machines will fail to remain up-to-date regardless of
any attempt made to fix the issue; simply because it becomes to diversive and
unmaintainable.
+ </para>
+
+ <section
id="PuppetWorkshop-IntroductionToConfigurationManagement-WhatIsConfigurationManagement-ConfigurationManagement">
+ <title>Configuration Management</title>
+ <para>
+ Generally speaking, with configuration management, it's about
managing the configuration of one or more organizational resources in order to have it be
in a state in which it can perform the operations required by, and possibly critical to,
the organization's operations.
+ </para>
+ <para>
+ In this workshop though, we are not going to explore
configuration management of a coffee machine. Instead we look at the computers in a
network running any platform but the one from a prominent proprietary North America-based
vendor. We are talking automation and further enhancement of Computer Systems
Administration.
+ </para>
+ <para>
+ When managing the operating system and software running on
mainframes, servers, desktop PCs and laptops, you may find yourself looking for answers to
questions such as:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ How do I manage what packages are installed on a
given system?
+ <itemizedlist>
+ <listitem>
+ <para>
+ How do I manage the configuration of
those packages (this software)?
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ How do I make sure these packages are
updated?
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ How do I make sure the services that every machine
needs to run are actually running?
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ How do I manage monitoring the services or a
machine's state?
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A job needs to run periodically (maybe via
<application>crontab</application>), but how do I make sure it is run, and how
can I change or remove the job later?
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Given different operating systems and operating
system versions, how do I make sure I apply the correct routine for adding a user,
starting a service, install/update/remove a package?
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section
id="PuppetWorkshop-IntroductionToConfigurationManagement-WhatIsConfigurationManagement-ConfigurationManagementRequirements">
+ <title>Configuration Management Requirements</title>
+ <para>
+ This section is about what you would want Configuration
Management to do for you:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <formalpara>
+ <title>Maintain consistency across
systems</title>
+ <para>
+ Consistency across systems is key in
understanding where a problem might come from. If each and every system is unique, you may
end up searching for unique aspects of the system's configuration in order to
determine the cause of a problem, while if systems are consistent to some extend, you may
have found the problem even before your users report it.
+ </para>
+ </formalpara>
+ <formalpara>
+ <title>Consistency !== Equality</title>
+ <para>
+ Of course keeping system consistent in their
configuration doesn't say all your systems should be entirely equal, because that
would not be feasible for many organizations and defeat the purpose of configuration
management. Needless to say though, having all systems be entirely unique defeats part of
the purpose of configuration management as well.
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>Categorize systems</title>
+ <para>
+ Categorizing systems into categories like (for
example) <emphasis>desktop</emphasis>, <emphasis>server</emphasis>
and/or <emphasis>laptop</emphasis>, helps in applying changes to one category,
such as installing <application>GNOME</application> or keeping systems
up-to-date according to a schedule that may (servers) or may not (desktops, laptops) need
a service or maintenance window.
+ </para>
+ </formalpara>
+ <formalpara>
+ <title>Different profiles</title>
+ <para>
+ More generally speaking, different profiles for
each of these categories may be defined as well, of course. A developer's desktop most
likely has different requirements then a publicly accessible booth at the reception desk.
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>Version Control</title>
+ <para>
+ Version control lets you keep track of changes
applied to the overall configuration management framework, which is important because
since you are managing different aspects of a number of systems, if something goes wrong
the changes applied to the configuration of puppet will most likely be the first clue as
to what caused the new problem and lets you recover relatively fast.
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>Overview of systems' tasks and
services</title>
+ <para>
+ Being able to quickly tell what a system does
exactly, and how it differs from another system not only aids in performing risk
assessments (impact of a given change), but may also help in determining the impact of a
change beforehand, as well as determine the impact of an unexpected system interruption.
Providing an example to the latter I suppose if you update httpd across systems (whether
tested or untested), but the new software version doesn't work as expected, a
configuration management framework should be able to quickly give you an overview of
impacted systems and services.
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>Updating systems</title>
+ <para>
+ Some systems can be updated irregularly, such as
desktop PCs, but need to be kept up-to-date nonetheless. Other systems need to have
service and/or maintenance windows, such as servers.
+ </para>
+ </formalpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
</section>
- <section
id="PuppetWorkshop-ConfigurationManagement-ProblemsWithConfigurationManagement">
- <title>Problems with Configuration Management?</title>
+ <section
id="PuppetWorkshop-IntroductionToConfigurationManagement-ProblemsWithoutConfigurationManagement">
+ <title>Problems without Configuration Management</title>
+ <para>
+ There's a number of challenges in applying configuration
management, such as:
+ </para>
<para>
- This is a first section
+ <orderedlist>
+ <listitem>
+ <formalpara>
+ <title>Different operating systems</title>
+ <para>
+ If you have a diverse organization in terms of the
operating systems your nodes run, applying the same thing to a set of different operating
systems is challenging in that adding a user or setting a password on one operating system
isn't the same as adding a user or setting a password on another operating system. Of
course the same applies to installing, updating or removing a package, and so forth. Of
course the more different operating systems you have, the harder managing any given
resource becomes.
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>Different distributions</title>
+ <para>
+ Although an organization may not have different
distributions running right now, sooner or later, an organization will migrate from one
distribution to another; That is practically inevitable. If an organization does have
different distributions running, practical problems such as the location of certain files
become evident, as well as different interfaces to resource-management (like adding a user
with <application>useradd</application> or
<application>adduser</application>).
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>Different versions of
distributions</title>
+ <para>
+ Different versions of distributions, or more
accurately the different versions of the utilities, as well as the configuration settings
for updated programs that come with the distributions, can form a challenge when or if the
organization does not have a proper configuration management framework in place. Note that
even though an organization may not have different versions of a distribution right now,
at some point the organization will need to upgrade to the next available release.
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>Different tasks to perform</title>
+ <para>
+ Each different system in an organization is
performing one or more tasks that may be unique to the system or may be shared between a
group of systems, but with many different tasks being performed throughout the
organization's infrastructure, keeping track of what system performs which task,
keeping these systems up to date and configuring them to have the required packages
installed for each of the tasks they perform, tackling the problem becomes harder.
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>Different ways to perform a
task</title>
+ <para>
+ Within an organization that has multiple servers
performing the same task, keeping a similar state or perform a task in a similar manner is
challenging in that without configuration management, you are most likely to find three or
more ways to purge old files from <filename>/tmp/</filename> and
<filename>/var/tmp/</filename>, for example. The same differentiation may
apply to how webservers' VirtualHost's are configured, or how a NFS share is
mounted (mount options in particular).
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>Different nodes</title>
+ <para>
+ This one goes to hardware-specific needs and
configuration. When each of the systems in an organization are not all of the same brand,
make and model, or each system has different harddisk layouts, or needs different
videocard drivers, you are basically keeping lists and making choices based on this list.
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>Different services</title>
+ <para>
+ Different services of course are configured
differently, as far as configuration file locations and syntax are concerned. However,
figuring out the best way to apply certain configuration to a system for each service is
less efficient without configuration management. You might adjust a script or two and/or
adjust the source repository from which you pull updates to each machine, but the changes
may turn out to only apply to that system that needed the exception to the rule instead of
focussing on a more general solution to the problem once, and apply that solution multiple
times, over and over again.
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>Interfaces to a system
resource</title>
+ <para>
+ This is probably the hardest one if you are not using
any configuration management framework. Given different operating systems, distributions
and/or distribution versions, in which case any combination of the three only makes the
problem harder to solve, you are most likely to encounter so many different ways to manage
a resource, that a simple script or routine cannot cover all of them. One example is
adding a user to the system, and making the user a group member of several groups. You may
find routines ranging from using <application>useradd</application> or
<application>adduser</application> depending on the distribution used, to
writing out ldifs from a template and using <application>ldapadd</application>
or <application>ldapmodify</application> depending on whether the user already
exists or not.
+ </para>
+ </formalpara>
+ </listitem>
+ </orderedlist>
</para>
+ </section>
+ <section
id="PuppetWorkshop-IntroductionToConfigurationManagement-NotSoTechnicalAspects">
+ <title>Not So Technical Aspects</title>
+ <para>
+ In addition to the problems you may encounter with or without
configuration management, there's a number of problems or challenges that are not so
technical, but you may want to see resolved by a configuration management utility;
+ </para>
+ <para>
+ <orderedlist>
+ <listitem>
+ <formalpara>
+ <title>Applying changes</title>
+ <para>
+ Applying changes to multiple machines at once may
become a problem depending on the size of the organization or the amount of control that
you have over systems, remotely. There was a time when changing the DNS servers for a set
of systems required one to log on to the console of each system and edit
<filename>/etc/resolv.conf</filename> manually. You can see the problem become
bigger if the organization does not have 20 systems, but 1200.
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>Keeping track of changes</title>
+ <para>
+ Another challenge is keeping track of the changes
applied to each system. Even with configuration management, errors can be made and systems
might behave unexpectedly, in which case you will want to know what changed on these
systems, and how to recover to an operational state. Keeping track of changes without a
configuration management framework however is a little harder, but with configuration
management, you have reports (changes applied to a system in a nice overview), and most
advisebly you have the configuration for Puppet stored in a Source Control Management
system, or SCM system, like CVS, SVN, Mercurial, or GIT.
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>Staging changes</title>
+ <para>
+ Staging changes is a huge must-have in case changes
are radical or might destroy a normal system's operation (even if temporary). For such
changes, you would want to test the changes first, and with Puppet, you get this in the
form of <emphasis>environments</emphasis>.
+ </para>
+ </formalpara>
+ </listitem>
+ </orderedlist>
+ </para>
</section>
</chapter>
- <chapter id="PuppetWorkshop-Puppet">
- <title>Puppet</title>
+ <chapter id="PuppetWorkshop-IntroductionToPuppet">
+ <title>Introduction To Puppet</title>
+ <para>
+ Puppet is a solution to the problems set forth in <xref
linkend="PuppetWorkshop-IntroductionToConfigurationManagement-ProblemsWithoutConfigurationManagement"
/>.
+ </para>
- <section id="PuppetWorkshop-Puppet-WhatDoesPuppetDo">
+ <section
id="PuppetWorkshop-IntroductionToPuppet-WhatDoesPuppetDo">
<title>What Does Puppet Do?</title>
<para>
- This is a first section
+ Puppet offers a high-level abstraction of system resources like you
would encounter on any given system, such as users, services and packages. Seeing as how
different operating systems and different distributions each have different interfaces,
so-called <emphasis>providers</emphasis> in puppet terms, to these system
resources, scripting a package to be installed, updated, removed or be of a certain
version includes a lot of <code>if-then-else</code> statements in a script
you'd write to manage that particular system resource, the package.
+ </para>
+ <para>
+ On Debian, Ubuntu and derivative distributions for example, the
package provider may be <application>apt</application>,
<application>dpkg</application>, <application>smart</application>,
<application>alien</application>,
<application>PackageKit</application>, while on Fedora, Red Hat and it's
derivatives, the package provider may be <application>rpm</application>,
<application>yum</application>,
<application>PackageKit</application>,
<application>apt</application> or
<application>smart</application>.
+ </para>
+ <para>
+ Another difference between distributions is how services can be
started, or configured to start up when the machine boots. A
<application>service</application> script may be available, or
<filename>/etc/init.d/</filename> may contain scripts to start and stop a
service. Also, some of these service providers may have <code>status</code>,
<code>reload</code> and <code>restart</code> command parameters,
whereas others may not have. Additionally, using
<application>chkconfig</application> to configure the runlevels the service
should be enabled or disabled in may not be available on all systems.
+ </para>
+ <para>
+ By abstracting these system resources into
<emphasis>types</emphasis>, Puppet takes on the headaches for most operating
system and distribution specific interfaces to managing these system resources. It knows,
or figures out all by itself, what provider to use given a
<emphasis>type</emphasis>.
+ </para>
+ <formalpara>
+ <title>Abstraction of system resources</title>
+ <para>
+ Abstraction of the system resources into so-called
<emphasis>types</emphasis> causes the administrator to only need to configure
a type, such as <emphasis>package</emphasis>,
<emphasis>user</emphasis>, <emphasis>cron</emphasis>, and so
forth. The configuration management utility itself will figure out what package manager
backend to use, whether it's apt, yum, rpm, dpkg, smart or PackageKit.
+ </para>
+ </formalpara>
+ <para>
+ Puppet example to ensure user
<emphasis>sysadmin</emphasis> exists on a system:
+ <screen>user { "sysadmin":
+ ensure => present
+}</screen>
+ </para>
+ <para>
+ Puppet example to ensure the <emphasis>ypbind</emphasis>
package is installed and the most recent version, <emphasis>ypbind</emphasis>
is correctly configured, and the <emphasis>ypbind</emphasis> service is
running:
+ <screen>package { "ypbind":
+ ensure => latest
+}
+
+file { "/etc/yp.conf":
+ source => "puppet://$server/files/yp.conf",
+ notify => Service["ypbind"],
+ require => Package["ypbind"]
+}
+
+service { "ypbind":
+ enable => true,
+ ensure => running,
+ require => [
+ File["/etc/yp.conf"],
+ Package["ypbind"]
+ ]
+}</screen>
+ </para>
+ <para>
+ The above example is called a
<emphasis>manifest</emphasis>, built out of
<emphasis>types</emphasis> (package, file, service), which, once defined in a
manifest, are referred to as <emphasis>resources</emphasis>. See also <xref
linkend="PuppetWorkshop-Appendix-Terminology" />
</para>
</section>
+ </chapter>
+
+ <chapter id="PuppetWorkshop-PuppetTerminology">
+ <title>Puppet Terminology</title>
+ <para>
+ Terminology used in this documentation. See also <xref
linkend="PuppetWorkshop-Appendix-Terminology" />
+ <itemizedlist>
+ <listitem>
+ <formalpara>
+ <title>class</title>
+ <para>
+ A class is a collection of resources applied to a node
with a single include statement. It groups together a comprehensible set of resources. A
class <emphasis>ypclient</emphasis> would manage the
<code>File["/etc/nsswitch.conf"]</code>,
<code>File["/etc/yp.conf"]</code>,
<code>Package["ypbind"]</code>, and
<code>Service["ypbind"]</code> resources.
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>fileserver</title>
+ <para>
+ The fileserver is where the puppet pulls files from. It
is normally integrated with the puppetmaster, but it can be an entirely different server,
too.
+ </para>
+ </formalpara>
+ <para>
+ The fileserver serves files to puppets that request them, but
it also serves <emphasis>templates</emphasis>, which are parsed on the
fileserver (puppetmaster), and passed on to the client as a whole new file.
+ </para>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>manifest</title>
+ <para>
+ The collection of classes, modules and resources that the
<xref linkend="PuppetWorkshop-PuppetTerminology-puppetmaster" /> uses to
distribute the appropriate configuration to a <xref
linkend="PuppetWorkshop-PuppetTerminology-puppet" />.
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>module</title>
+ <para>
+ A module is a placeholder for files, manifests, plugins
and templates. Creating a module has numerous advantages such as separate version control,
separate staging from development through testing to production, and so forth.
+ </para>
+ </formalpara>
+ <para>
+ <emphasis>See also</emphasis>: <xref
linkend="PuppetWorkshop-HowToUsePuppet-Modules" />, <xref
linkend="PuppetWorkshop-HowToUsePuppet-Plugins" />
+ </para>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>node</title>
+ <para>
+ The client, a node, is an operating system instance
running the puppet client application. This can be a regular operating system running
directly on top of actual hardware, a virtual guest as well as a virtual host.
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara
id="PuppetWorkshop-PuppetTerminology-puppet">
+ <title>puppet</title>
+ <para>
+ The client, a node, runs the
<application>puppetd</application> daemon or service, and is referred to as
the <emphasis>puppet</emphasis>
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara
id="PuppetWorkshop-PuppetTerminology-puppetmaster">
+ <title>puppetmaster</title>
+ <para>
+ The puppetmaster is the node that runs the server-side
application to a puppet setup.
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>resource</title>
+ <para>
+ A resource is an instantiated <xref
linkend="PuppetWorkshop-PuppetTerminology-type" />
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>system resource</title>
+ <para>
+ A system resource is a resource available on the node
whether it is managed by puppet or not. Unlike in other cases, this term does not as much
to system hardware resources such as the CPU or memory available to the operating system,
because that.
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara
id="PuppetWorkshop-PuppetTerminology-type">
+ <title>type</title>
+ <para>
+ definition
+ </para>
+ </formalpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </chapter>
- <section id="PuppetWorkshop-Puppet-HowDoesItWork">
- <title>How Does It Work?</title>
+ <chapter id="PuppetWorkshop-HowPuppetWorks">
+ <title>How Puppet Works</title>
+ <para>
+ This is an overview of how puppet works -in a working setup.
+ </para>
+ <para>
+ <orderedlist>
+ <listitem>
+ <formalpara>
+ <title>The puppet starts for the first
time</title>
+ <para>
+ It generates a certificate using the node's FQDN.
+ </para>
+ </formalpara>
+ <note>
+ <para>
+ Although not required, it is strongly recommended to have
the client use a FQDN that is registered in DNS (forward as well as reverse).
+ </para>
+ </note>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>The puppet submits the certificate to the
puppetmaster</title>
+ <para>
+ The puppetmaster, also the Certificate Authority, or
<emphasis>puppetca</emphasis>, needs to sign the certificate before the client
can be considered authenticated.
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>The puppet waits 300 seconds for a signed
certificate</title>
+ <para>
+ It this configurable timeout of 300
seconds<footnote><para>Specify the timeout with <code>--waitforcert
[seconds]</code></para></footnote> has passed, the puppet quits.
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>The puppetmaster signs the
certificate</title>
+ <para>
+ To do so, you can either configure the puppetmaster to
automatically sign certificates or sign manually. Automatically signing certificates is
generally a very bad idea. To manually sign a certificate, use:
+ </para>
+ </formalpara>
+ <para>
+ <screen># <userinput>puppetca --sign
<fqdn></userinput></screen>
+ </para>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>The puppet receives the signed
certificate</title>
+ <para>
+ Immediately thereafter, the puppet starts a configuration
run.
+ </para>
+ </formalpara>
+ <warning>
+ <para>
+ The time on both the puppetmaster and the puppet must be
within 5 minutes of eachother as the certificate generated and signed has a validity
period. If the difference in time of these two nodes is more then 5 minutes, you will get
a "Certificates not trusted" type of error.
+ </para>
+ </warning>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>The puppet generates all the
facts</title>
+ <para>
+ Most configurations rely on client information to make
decisions. When the Puppet client starts, it loads the Facter Ruby library, collects all
of the facts that it can, and passes those facts to the interpreter. When you use Puppet
over a network, these facts are passed over the network to the server and the server uses
them to compile the client's configuration.
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>The puppetmaster parses it's
manifests</title>
+ <para>
+ The puppetmaster parses through all it's manifests,
including the manifests not applicable to the puppet that is polling. It only sends out
the manifest applicable to the puppet polling, however.
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>The puppet receives the manifests</title>
+ <para>
+ When the puppet receives the manifests, it may still
contain variables such as <code>$hostname</code>,
<code>$operatingsystem</code> and others, which the puppet fills out with the
appropriate values.
+ </para>
+ </formalpara>
+<!-- <warning>
+ <para>
+ All variables in the manifest sent to the client should
be based on facts rather then fiction.
+ </para>
+ </warning>-->
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>The puppet applies the manifest</title>
+ <para>
+ While the puppet applies the manifest, it pulls files
from the puppetmaster's <emphasis>fileserver</emphasis> after checking the
local checksum against the remote checksum. When running with debug output, this will show
as
+ <screen>debug: Calling fileserver.list
+debug: //Node[node1.example.com]/File[/tmp/foo]/checksum: Initializing checksum hash
+debug: //Node[node1.example.com]/File[/tmp/foo]: Creating checksum
{md5}85e53dc9439253a1ec9ca87aeffd9b0b
+debug: Calling fileserver.describe</screen>
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>Files that are replaced are backed
up</title>
+ <para>
+ The puppet sends a copy of the files it replaces back to
the puppetmaster.
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>The puppet reports to the
puppetmaster</title>
+ <para>
+ A detailed report of what the puppet has done with the
manifests is sent back to the puppetmaster.
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>The puppet waits for 30 minutes</title>
+ <para>
+ para
+ </para>
+ </formalpara>
+ </listitem>
+ </orderedlist>
+ </para>
+ <para>
+ A puppet setup is comprised out of the following parts:
+ </para>
+ <formalpara>
+ <title>The Puppetmaster</title>
<para>
- This is a first section
+ The puppetmaster of course is the core element in a puppet setup. Not
only is it responsible for the handing over the manifest to the client, it also takes care
of serving the files needed by the manifest, as well as
</para>
+ </formalpara>
+ </chapter>
- </section>
+ <chapter id="PuppetWorkshop-PuppetFeatures">
+ <title>Puppet Features</title>
+ <para>
+ paragraph
+ </para>
+ </chapter>
- <section id="PuppetWorkshop-Puppet-Troubleshooting">
- <title>And What If It Doesn't?</title>
+ <chapter id="PuppetWorkshop-TroubleshootingPuppet">
+ <title>Troubleshooting Puppet</title>
+ <para>
+ This section is about troubleshooting the puppetmaster and puppet
+ </para>
+ </chapter>
+
+ <chapter id="PuppetWorkshop-SettingUpPuppet">
+ <title>Setting Up Puppet</title>
+ <para>
+ In this section, we are going to set up a puppetmaster, and a puppet
client. The puppetmaster is going to run the <emphasis>mongrel</emphasis>
server-type, for setting up a puppetmaster for larger environments.
+ </para>
+
+ <section id="PuppetWorkshop-SettingUpPuppet-Installation">
+ <title>Installation</title>
<para>
- This is a first section
+ Install the required packages for the puppetmaster:
</para>
+ <formalpara>
+ <title>Smaller organizations (< ~25
clients)</title>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The puppetmaster.
+ </para>
+ <para>
+ <screen># <userinput>yum install
puppet-server</userinput></screen>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ (optional) A database server (one of MySQL, SQLite3
or Postgresql), and the appropriate Ruby library. During this workshop, we use MySQL.
+ </para>
+ <para>
+ <screen># <userinput>yum install
mysql-server ruby-mysql</userinput></screen>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ (optional) The Ruby RRDtool library.
+ </para>
+ <para>
+ <screen># <userinput>yum install
ruby-RRDtool</userinput></screen>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </formalpara>
+ <formalpara>
+ <title>Larger organizations (> ~25
clients)</title>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ A webserver capable of performing as a frontend SSL
reverse proxy load balancer, such as the Apache HTTPd webserver.
+ </para>
+ <para>
+ <screen># <userinput>yum install
httpd</userinput></screen>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The Ruby mongrel library
+ </para>
+ <para>
+ <screen># <userinput>yum install
rubygem-mongrel</userinput></screen>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The puppetmaster.
+ </para>
+ <para>
+ <screen># <userinput>yum install
puppet-server</userinput></screen>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ (optional) A database server (one of MySQL, SQLite3
or Postgresql), and the appropriate Ruby library. During this workshop, we use MySQL.
+ </para>
+ <para>
+ <screen># <userinput>yum install
mysql-server ruby-mysql</userinput></screen>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ (optional) The Ruby RRDtool library.
+ </para>
+ <para>
+ <screen># <userinput>yum install
ruby-RRDtool</userinput></screen>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </formalpara>
</section>
- <section id="PuppetWorkshop-Puppet-HowToSetItUp">
- <title>How To Set It Up (right)?</title>
+ <section id="PuppetWorkshop-SettingUpPuppet-Configuration">
+ <title>Configuration</title>
<para>
- This is a first section
+ para
</para>
+ <section
id="PuppetWorkshop-SettingUpPuppet-Configuration-Puppetmaster">
+ <title>Configuring the Puppetmaster</title>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Configure in /etc/puppet/puppet.conf section
[puppetmasterd] certname and certdnsaliases
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Configure a minimal manifest (site.pp)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Start the puppetmaster once (generate certificates)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ (optional) configure reporting
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ (optional) configure storeconfigs
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ (optional) configure graphing
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ The configuration file for puppet and puppetmaster is
<filename>/etc/puppet/puppet.conf</filename>. It is a file in INI-like format
with sections, keys and values.
+ </para>
+ <formalpara>
+ <title>First run relevant settings</title>
+ <para>
+ For the first run of the puppetmaster, we need to configure
the following:
+ <itemizedlist>
+ <listitem>
+ <formalpara>
+ <title>certname</title>
+ <para>
+ The puppetmaster certificate's Common
Name (CN), for which by default the system's hostname is used. The hostname of the
system is a pretty reasonable value.
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>certdnsnames</title>
+ <para>
+ A colon (<literal>:</literal>)
seperated list of DNS names resolving to the puppetmaster. Include here:
+ <orderedlist>
+ <listitem>
+ <para>
+ The short hostname of the system,
using the output of: <screen># <userinput>hostname
-s</userinput></screen>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+
<literal>puppet</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+
<literal>puppet</literal>, followed by the DNS domain name of the system,
using the output of <screen>#
<userinput>dnsdomainname</userinput></screen>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Any other hostname or fully
qualified domain name you want to use for the puppetmaster.
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <para>
+ The locations where puppet seeks it's
configuration and puts it's transitional data. The most important setting is
<literal>vardir</literal>, which should be set to
<filename>/var/lib/puppet/</filename>. Further settings include:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <code>logdir =
/var/log/puppet/</code>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <code>rundir =
/var/run/puppet/</code>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <code>ssldir =
$vardir/ssl/</code>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <note>
+ <para>
+ If you used a package to install puppet, the
defaults. It is the upstream puppet package that cannot coher with each and every
distribution or operating system it is available for, and therefor has a set of defaults
that will work, but will need to be changed on most platforms.
+ </para>
+ </note>
+ </listitem>
+ <listitem>
+ <para>
+ Whether or not to use autosigning of
certificates, using <code>[puppetca], autosign = false, true</code>. The
default is to <emphasis>not</emphasis> use autosigning.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Another setting to check is whether or not this
puppetmaster is going to be the Certificate Authority (<code>[puppetmasterd], ca =
<replaceable>false, true</replaceable></code>). The default is often set
to <code>true</code>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </formalpara>
+ <formalpara>
+ <title>Other relevant settings</title>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The location of tagmail.conf, <code>[main],
tagmap = <replaceable>/path/to/tagmail.conf</replaceable></code>, for
reporting changes applied to puppets, via email.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A list of environments using a comma seperated
list, in <code>[puppetmasterd], environments =
<replaceable>environments</replaceable></code>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ whether or not to use reporting, and what
reporting to use (tagmail, store, rrdgraph)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ what type of configuration store to use (sqlite3,
mysql, postgresql)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ database settings for use with storeconfigs
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </formalpara>
+ </section>
+
+ <section
id="PuppetWorkshop-SettingUpPuppet-Configuration-SSLFrontendReverseProxyLoadBalancer">
+ <title>Configuring the SSL Frontend Reverse Proxy Load
Balancer</title>
+ <para>
+ para
+ </para>
+ </section>
+
+ <section
id="PuppetWorkshop-SettingUpPuppet-Configuration-DatabaseServer">
+ <title>Configuring the Database Server</title>
+ <para>
+ para
+ </para>
+
+ <section
id="PuppetWorkshop-SettingUpPuppet-Configuration-DatabaseServer-SQLite3">
+ <title>SQLite3</title>
+ <para>
+ para
+ </para>
+ </section>
+
+ <section
id="PuppetWorkshop-SettingUpPuppet-Configuration-DatabaseServer-MySQL">
+ <title>MySQL</title>
+ <para>
+ para
+ </para>
+ </section>
+
+ <section
id="PuppetWorkshop-SettingUpPuppet-Configuration-DatabaseServer-Postgresql">
+ <title>PostgreSQL</title>
+ <para>
+ para
+ </para>
+ </section>
+
+ </section>
+
</section>
- <section id="PuppetWorkshop-Puppet-HowToUseIt">
- <title>How To Use It?</title>
+ </chapter>
+
+ <chapter id="PuppetWorkshop-HowToUsePuppet">
+ <title>How To Use Puppet</title>
+ <para>
+ This is a first section
+ </para>
+
+ <section id="PuppetWorkshop-HowToUsePuppet-Modules">
+ <title>Using Modules</title>
<para>
- This is a first section
+ About using modules
</para>
-
</section>
- <section id="PuppetWorkshop-Puppet-WhatElseCanItDo">
- <title>What Else Can It Do?</title>
+ <section id="PuppetWorkshop-HowToUsePuppet-Plugins">
+ <title>Using Plugins</title>
<para>
- This is a first section
+ About the use of plugins
</para>
+ </section>
+
+ </chapter>
+
+ <chapter id="PuppetWorkshop-OtherThingsToDoWithPuppet">
+ <title>Other Things To Do With Puppet</title>
+ <para>
+ This is a first section
+ </para>
+ <section
id="PuppetWorkshop-OtherThingsToDoWithPuppet-WritingCustomTypes">
+ <title>Writing Custom Types</title>
+ <para>
+ paragraph
+ </para>
</section>
- <section id="PuppetWorkshop-Puppet-BestPractices">
- <title>Best Practices</title>
+ <section
id="PuppetWorkshop-OtherThingsToDoWithPuppet-WritingCustomFacts">
+ <title>Writing Custom Facts</title>
<para>
- This is a first section
+ paragraph
</para>
+ </section>
+ <section
id="PuppetWorkshop-OtherThingsToDoWithPuppet-WritingCustomFunctions">
+ <title>Writing Custom Functions</title>
+ <para>
+ paragraph
+ </para>
</section>
</chapter>
+
+ <chapter id="PuppetWorkshop-BestPractices">
+ <title>Best Practices</title>
+ <para>
+ This is a first section
+ </para>
+ </chapter>
+
</part>
<xi:include href="Course-Appendix.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />