Using modules

One of the most important things you can do to make your Puppet manifests clearer and more maintainable is to organize them into modules.

Modules are self-contained bundles of Puppet code that include all the files necessary to implement a thing. Modules may contain flat files, templates, Puppet manifests, custom fact declarations, augeas lenses, and custom Puppet types and providers.

Separating things into modules makes it easier to reuse and share code; it's also the most logical way to organize your manifests. In this example, we'll create a module to manage memcached, a memory caching system commonly used with web applications.

How to do it…

Following are the steps to create an example module:

1. We will use Puppet's module subcommand to create the directory structure for our new module:

   t@cookbook:~$ mkdir -p .puppet/modules
   t@cookbook:~$ cd .puppet/modules
   t@cookbook:~/.puppet/modules$ puppet module generate thomas-memcached
   We need to create a metadata.json file for this module.  Please answer the following questions; if the question is not applicable to this module, feel free to leave it blank. Puppet uses Semantic Versioning (semver.org) to version modules.What version is this module?  [0.1.0]
   --> Who wrote this module?  [thomas]
   --> What license does this module code fall under?  [Apache 2.0]
   --> How would you describe this module in a single sentence?
   --> A module to install memcached Where is this module's source code repository?
   --> Where can others go to learn more about this module?
   --> Where can others go to file issues about this module?
   --> 
   ----------------------------------------
   {
     "name": "thomas-memcached",
     "version": "0.1.0",
     "author": "thomas",
     "summary": "A module to install memcached",
     "license": "Apache 2.0",
     "source": "",
     "issues_url": null,
     "project_page": null,
     "dependencies": [
       {
         "version_range": ">= 1.0.0",
         "name": "puppetlabs-stdlib"
       }
     ]
   }
   ----------------------------------------
   About to generate this metadata; continue? [n/Y]
   --> y
   Notice: Generating module at /home/thomas/.puppet/modules/thomas-memcached...
   Notice: Populating ERB templates...
   Finished; module generated in thomas-memcached.
   thomas-memcached/manifests
   thomas-memcached/manifests/init.pp
   thomas-memcached/spec
   thomas-memcached/spec/classes
   thomas-memcached/spec/classes/init_spec.rb
   thomas-memcached/spec/spec_helper.rb
   thomas-memcached/README.md
   thomas-memcached/metadata.json
   thomas-memcached/Rakefile
   thomas-memcached/tests
   thomas-memcached/tests/init.pp
   

   This command creates the module directory and creates some empty files as starting points. To use the module, we'll create a symlink to the module name (memcached).

   t@cookbook:~/.puppet/modules$ ln –s thomas-memcached memcached
   

2. Now, edit memcached/manifests/init.pp and change the class definition at the end of the file to the following. Note that puppet module generate created many lines of comments; in a production module you would want to edit those default comments:

   class memcached {
     package { 'memcached':
       ensure => installed,
     }
   
     file { '/etc/memcached.conf':
       source  => 'puppet:///modules/memcached/memcached.conf',
       owner   => 'root',
       group   => 'root',
       mode    => '0644',
       require => Package['memcached'],
     }
     service { 'memcached':
       ensure  => running,
       enable  => true,
       require => [Package['memcached'],
                   File['/etc/memcached.conf']],
     }
   }

3. Create the modules/thomas-memcached/files directory and then create a file named memcached.conf with the following contents:

   -m 64
   -p 11211
   -u nobody
   -l 127.0.0.1

4. Change your site.pp file to the following:

   node default {
     include memcached
   }

5. We would like this module to install memcached. We'll need to run Puppet with root privileges, and we'll use sudo for that. We'll need Puppet to be able to find the module in our home directory; we can specify this on the command line when we run Puppet as shown in the following code snippet:

   t@cookbook:~$ sudo puppet apply --modulepath=/home/thomas/.puppet/modules /home/thomas/.puppet/manifests/site.pp
   Notice: Compiled catalog for cookbook.example.com in environment production in 0.33 seconds
   Notice: /Stage[main]/Memcached/File[/etc/memcached.conf]/content: content changed '{md5}a977521922a151c959ac953712840803' to '{md5}9429eff3e3354c0be232a020bcf78f75'
   Notice: Finished catalog run in 0.11 seconds

6. Check whether the new service is running:

   t@cookbook:~$ sudo service memcached status
   [ ok ] memcached is running.

How it works…

When we created the module using Puppet's module generate command, we used the name thomas-memcached. The name before the hyphen is your username or your username on Puppet forge (an online repository of modules). Since we want Puppet to be able to find the module by the name memcached, we make a symbolic link between thomas-memcached and memcached.

Modules have a specific directory structure. Not all of these directories need to be present, but if they are, this is how they should be organized:

modules/
  └MODULE_NAME/  never use a dash (-) in a module name
     └examples/ example usage of the module
     └files/ flat files used by the module
     └lib/
        └facter/ define new facts for facter
        └puppet/
           └parser/
              └functions/ define a new puppet function, like sort() 
           └provider/ define a provider for a new or existing type
           └util/ define helper functions (in ruby)
           └type/ define a new type in puppet
     └manifests/
        └init.pp  class MODULE_NAME { }
     └spec/ rSpec tests
     └templates/ erb template files used by the module

All manifest files (those containing Puppet code) live in the manifests directory. In our example, the memcached class is defined in the manifests/init.pp file, which will be imported automatically.

Inside the memcached class, we refer to the memcached.conf file:

file { '/etc/memcached.conf':
  source => 'puppet:///modules/memcached/memcached.conf',
}

The preceding source parameter tells Puppet to look for the file in:

MODULEPATH/ (/home/thomas/.puppet/modules)

└memcached/

└files/

└memcached.conf

There's more…

Learn to love modules because they'll make your Puppet life a lot easier. They're not complicated, however, practice and experience will help you judge when things should be grouped into modules, and how best to arrange your module structure. Modules can hold more than manifests and files as we'll see in the next two sections.

Templates

If you need to use a template as a part of the module, place it in the module's templates directory and refer to it as follows:

file { '/etc/memcached.conf':
  content => template('memcached/memcached.conf.erb'),
}

Puppet will look for the file in:

MODULEPATH/memcached/templates/memcached.conf.erb

Facts, functions, types, and providers

Modules can also contain custom facts, custom functions, custom types, and providers.

For more information about these, refer to Chapter 9, External Tools and the Puppet Ecosystem.

Third-party modules

You can download modules provided by other people and use them in your own manifests just like the modules you create. For more on this, see Using Public Modules recipe in Chapter 7, Managing Applications.

Module organization

For more details on how to organize your modules, see puppetlabs website:

http://docs.puppetlabs.com/puppet/3/reference/modules_fundamentals.html

See also

• The Creating custom facts recipe in Chapter 9, External Tools and the Puppet Ecosystem
• The Using public modules recipe in Chapter 7, Managing Applications
• The Creating your own resource types recipe in Chapter 9, External Tools and the Puppet Ecosystem
• The Creating your own providers recipe in Chapter 9, External Tools and the Puppet Ecosystem