Start writing modules for *nix
In this guide, you modify a Forge module, and use the Puppet Development Kit to write a module and unit test it. This helps you become more familiar with Puppet modules and module development.
Modules are reusable chunks of Puppet code and are the basic building blocks of any Puppet Enterprise (PE) deployment. Some modules from the Forge might precisely fit your needs, but many are almost --- but not quite --- what you need. You might want to adapt pre-written modules to suit your deployment's requirements. In other cases, you might need to write your own modules from scratch.
Module location
By default, Puppet keeps modules in /etc/puppetlabs/code/environments/production/modules
. This includes modules
installed by PE, those that you download
from the Forge, and those you write
yourself. You can configure this path with the modulepath
setting in puppet.conf
.
/opt/puppetlabs/puppet/modules
. Don't
modify anything in this directory or add modules of your own to it.Module structure
Modules are directory trees that contain manifests, templates, and other files.
These files are in the puppetlabs-apache
module:
-
apache/
(the module name)-
manifests/
-
init.pp
(contains theapache
class) -
php.pp
(contains thephp
class to install PHP for Apache) -
vhost.pp
(contains the Apache virtual hosts class)
-
-
templates/
-
vhost/
-
_file_header.erb
(contains the vhost template, managed by PE)
-
-
-
Every manifest (.pp) file contains a single class. File names map to
class names in a predictable way: init.pp
contains a class with the same name as the module, in this case
apache
. <NAME>.pp
contains a class called <MODULE NAME>::<NAME>
. <NAME>/<OTHER NAME>.pp
contains <MODULE NAME>::<NAME>::<OTHER
NAME>
.
Many modules, including Apache, contain directories other than manifests
and templates
. For simplicity's sake, we do not cover them in this
introductory guide.
Edit a module's manifest and use the edited module
Modules from the Forge provide a great basis for common tasks. You can configure them to meet your specific needs.
These instructions assume you've installed PE, at least one *nix agent node, and the puppetlabs-apache
module.
In this simplified exercise, you modify a template from the
puppetlabs-apache module, specifically vhost.conf.erb
, to include some simple variables automatically populated
with facts about your node.
As you can see, PE has used Facter to retrieve some key facts about your node, and then used those facts to populate the header of your vhost template.
Write a new module
Write, validate, and test an example module for PE on *nix systems with Puppet Development Kit (PDK).
Make sure you've installed:
- PE
- At least one *nix agent node
- The puppetlabs-apache module
-
Puppet Development Kit on your master. See PDK installation instructions.
You must be logged in as root or administrator on your nodes.
Create a pe_getstarted_app
module that manages a PHP-based web app running on an Apache virtual host.
Create a module class
Write, test, and deploy a module class for an example module.
Make sure you have generated
the pe_getstarted_app
module
as described in the Write a
module topic.
After creating your class, you are ready to validate and unit test it.
Validate and unit test a class
Validate and unit test a class in an example module.
When you add code to a module, always validate and unit test it. PDK creates unit test directories and templates, and then you write the unit tests you need. For this example, we've provided an rspec unit test. To learn more about how to write unit tests, see rspec-puppet documentation.
Adding your module class to nodes
Add the class from your example module to nodes in the console.
You can now add your new module's class to the console and apply it to nodes, following the workflow in the Adding classes getting started guide.
Congratulations! Your first module is up and running. There are plenty of additional resources about modules and the creation of modules that you can reference. Check out documentation about Puppet Development Kit, module fundamentals, the modulepath, the Beginner's guide to modules, and the Puppet Forge.