The Power of Puppet

Prerequisites

  • Welcome Quest

Quest Objectives

  • Using existing Puppet modules, configure the Learning VM to serve a web version of the Quest Guide.
  • Learn how the Puppet Enterprise (PE) Console's node classifier can manage the Learning VM's configuration.

Getting Started

In this quest you will use the Puppet Enterprise (PE) Console in conjunction with existing modules to cut away much of the complexity of a common configuration task. You'll configure the Learning VM to serve the content of this Quest Guide as a locally accessible static HTML website. We'll show you how you can Puppet and freely available Puppet modules to fully automate the process instead of writing code or using standard terminal commands.

As you go through this quest, remember that while Puppet can simplify many tasks, it's a powerful and complex tool. There's a lot to learn if you want to use it to its full potential. We will explain concepts as needed to complete and understand each task in this quest, but sometimes we'll hold off on a fuller explanation of some detail until a later quest. Don't worry if you don't feel like you're getting the whole story right away; keep at it and we'll get there when the time is right!

When you're ready to get started, type the following command:

quest --start power 

Forging Ahead

A module is a bundle of Puppet code packaged along with the other files and data you need manage some aspect of a system. Need to set up NTP? There's a module for that. Manage system users? That too. But likely you'll want to do both of these things and more. Modules let you mix and match reusable bits of Puppet code to make achieving your desired configuration as painless as possible. Modules are designed to be, well, modular.

But where do these modules come from? The Puppet Forge is a public repository of modules contributed by members of the Puppet community, including many written and maintained by Puppet Labs employees and partners. The Forge also includes a list PE Supported Modules, which Puppet Labs has rigorously tested and is committed to supporting and maintaining through their lifecycle.

Task 1 :

To get started setting up the Quest Guide website, you'll need to download and install Puppet Labs' Apache module from the Forge. (If you're offline or behind a firewall, check the aside below for instructions on using the cached version of the module.)

The apache module gives you everything you need to automate installing, configuring, and starting an Apache webserver. In your terminal, enter the following command to install the module:

puppet module install puppetlabs-apache

Offline?

If you don't have internet access, run the following terminal commands to used a cached version of the module:

puppet module install /usr/src/forge/puppetlabs-apache-*.tar.gz --ignore-dependencies  

This command tells Puppet to download the Puppet Labs apache module from the Forge and place it in the directory specified as Puppet's modulepath. The modulepath defines the directory on your Puppet Master where Puppet saves modules you install and accesses modules you already have installed. For Puppet Enterprise, this defaults to /etc/puppetlabs/puppet/modules/.

Great job! You've just installed your first module from the Forge.

To help set up the Quest Guide website, we've also prepared an lvmguide module. It's already in the VM's module path, so there's no need to fetch it from the Forge. This small lvmguide module draws on some resources from the Apache module and uses some code and content of its own to finish the configuration of the Quest Guide website.

The lvmguide and Apache modules

Before using these modules, you should know a little more about how they work.

The lvmguide module includes Puppet code that defines an lvmguide class. In Puppet, a class is simply a named block of Puppet code organized in a way that defines a set of associated system resources. A class might install a package, customize an associated configuration file for that package, and start a service provided by that package. These are related and interdependent processes, so it makes sense to organize them into a single configurable unit: a class.

Despite some superficial similarities, Puppet's classes aren't like the classes in Object Oriented programming. You'll just get confused if you think of them this way!

While a module can include many classes, it will always have a main class that shares the name of the module. This class serves as the access point for the module's functionality and calls on other classes within the module or from pre-requisite modules as needed.

Put your Modules to Use

In order to configure the Learning VM to serve you the Quest Guide website, you'll need to classify it with the lvmguide class. Classification tells Puppet which classes to apply to which machines in your infrastructure. Though there are a few different ways to classify nodes, we'll be using the PE Console's node classifier for this quest.

To access the PE Console you'll need the Learning VM's IP address. Remember, you can use the facter tool packaged with PE.

facter ipaddress

You can see a list of all the system facts accessible through facter by running the `facter -p` command.

Open a web browser on your host machine and go to https://<ip-address>, where <ip-address> is the Learning VM's IP address. (Be sure to include the s in https)

If your browser gives you a security notice because the certificate is self-signed, go ahead and click accept to continue to the PE Console.

When prompted, use the following credentials to log in:

Username: puppet@example.com
Password: learningpuppet

Figure

You're in! Now that you have access to the PE Console, we'll go over the steps you'll take to classify the "learn.localdomain" node (i.e. the Learning VM) with the lvmguide class.

Add a Class

First, you need to add the lvmguide class to the list of classes available to the PE Console.

To do this, click the Add classes button on the Classes panel. (You may need to scroll to the bottom of the page to find the panel.)

Figure

Type lvmguide in the "Filter the list below" input box, and check the checkbox by the lvmguide class that appears in the list.

Figure

Now click the "Add selected classes" button.

Figure

You should see a verification message at the top of the PE Console and the the lvmguide class will appear in the list of available classes on the left side of the console interface.

Classify a Node

Now that the lvmguide class is available, you can use it to classify the node learn.localdomain.

Click on the "Nodes" menu item in the navigation menu. (You may need to scroll to the top of the page to see the navigation menu.)

Figure

Click on the learn.localdomain node hyperlink. (This should be the only one listed since the Learning VM is the only node you're managing with Puppet Enterprise.)

Figure

Once you're on the node page for learn.localdomain, click the "Edit" button located in the top-right corner of the screen.

Figure

In the Classes section, type lvmguide in the "add a class" input box

Figure

Click the "Update" button at the bottom.

Figure

Excellent! If everything went according to plan, you've successfully classified the learn.localdomain node with the lvmguide class.

Run Puppet

Now that you have classified the learn.localdomain node with the lvmguide class, Puppet knows how the system should be configured. But it won't make any changes until a Puppet run occurs.

The Puppet agent daemon runs in the background on any nodes you manage with Puppet. Every 30 minutes, the Puppet agent daemon requests a catalog from the Puppet Master. The Puppet Master parses all the classes applied to that node and builds the catalog to describes how the node is supposed to be configured. It returns this catalog to the node's Puppet agent, which then applies any changes necessary to bring the node into the line with the state described by the catalog.

Task 3 :

Instead of waiting for the Puppet agent to make its scheduled run, use the puppet agent tool to trigger one yourself. In your terminal, type the following command:

puppet agent --test

Please note this may take about a minute to run. This is about the time it takes for the software packages to be downloaded and installed as needed. After a brief delay, you will see text scroll by in your terminal indicating that Puppet has made all the specified changes to the Learning VM.

Check out the Quest Guide! In your browsers address bar, type the following URL: http://<ip-address>. Though the IP address is the same, using https will load the PE Console, while http will load the Quest Guide as a website.

From this point on you can either follow along with the website or with the PDF, whichever works best for you.

IP Troubleshooting

The website for the quest guide will remain accessible for as long as the VM's IP address remains the same. If you move your computer or laptop to a different network, or if you suspend your laptop and resumed work on the Learning VM after a while, the website may not be accessible.

In case any of the above issues happen, and you end up with a stale IP address, run the following commands on the Learning VM to get a new IP address. (Remember, if you're ever unable to establish an SSH session, you can log in directly through the interface of your virtualization software.)

Refresh your DHCP lease:

service network restart

Find your IP address:

facter ipaddress

Explore the lvmguide Class

To understand how the lvmguide class works, you can take a look under the hood. In your terminal, use the cd command to navigate to the module directory. (Remember, cd for 'change directory.')

cd /etc/puppetlabs/puppet/modules

Next, open the init.pp manifest.

nano lvmguide/manifests/init.pp
class lvmguide (
  $document_root = '/var/www/html/lvmguide',
  $port = '80',
) {
  
  class { 'apache': 
    default_vhost => false,
  }
  
  apache::vhost { 'learning.puppetlabs.vm':
    port    => $port,
    docroot => $document_root,
  }

  file { '/var/www/html/lvmguide':
    ensure  => directory,
    owner   => $::apache::params::user,
    group   => $::apache::params::group,
    source  => 'puppet:///modules/lvmguide/html',
    recurse => true,
    require => Class['apache'],
  }

}

(To exit out of the file, use the command control-x in nano, or :q! in vim.)

Don't worry about understanding each detail of the syntax just yet. For now, we'll just give you a quick overview so the concepts won't be totally new when you encounter them later on.

Class Title and Parameters:

class lvmguide (
  $document_root = '/var/www/html/lvmguide',
  $port = '80',
) {

The class lvmguide takes two parameters: $document_root and $port. The default values are set as /var/www/html/lvmguide and 80.

Include the apache module's apache class:

  class { 'apache': 
    default_vhost => false,
  }

The lvmguide class declares another class: apache. Puppet knows about the apache class because it is defined by the apache module you installed earlier. The default_vhost parameter for the apache class is set to false. This is all the equivalent of saying "Set up Apache, and don't use the default VirtualHost because I want to specify my own."

Include the apache module's vhost class:

  apache::vhost { 'learning.puppetlabs.vm':
    port    => $port,
    docroot => $document_root,
  }

This block of code declares the apache::vhost class for the Quest Guide with the title learning.puppetlabs.vm, and with $port and $docroot set to those class parameters we saw earlier. This is the same as saying "Please set up a VirtualHost website serving the 'learning.puppetlabs.vm' website, and set the port and document root based on the parameters from above."

Manage the files for our content:

  file { '/var/www/html/lvmguide':
    ensure  => directory,
    owner   => $::apache::params::user,
    group   => $::apache::params::group,
    source  => 'puppet:///modules/lvmguide/html',
    recurse => true,
    require => Class['apache'],
  }

Finally, the class manages the content for the website. It ensures that the directory /var/www/html/lvmguide exists and that its contents are managed recursively. The source => line tell Puppet to copy the content for this directory from an html directory in the lvmguide module.

It may seem like there's a lot going on here, but once you have a basic understanding of the syntax, a quick read-through will be enough to get the gist of well-written Puppet code. (We often talk about Puppet's DSL as self-documenting code.)

Repeatable, Portable, Testable

It's cool to install and configure an Apache httpd web server with a few lines of code and some clicks in the console, but keep in mind that the best part can't be shown with the Learning VM: once the lvmguide module is installed, you can apply the lvmguide class to as many nodes as you like, even if they have different specifications or run different operating systems.

And once a class is deployed to your infrastructure, Puppet gives you the ability to manage the configuration from a single central point. You can implement your updates and changes in a test environment, then easily move them into production.

Review

Great job on completing the quest! You should now have a good idea of how to download exising modules from the Forge and use the PE Console node classifier to apply them to a node. You also learned how to use the puppet agent --test command to manually trigger a puppet run.

Though we'll go over many of the details of the Puppet DSL in later quests, you had your first look at a Puppet class, and some of the elements that make it up.