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@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" />