Module of the Week: BenoitCattie/nginx – Basic nginx configuration

by Kelsey Hightower|14 February 2012

Welcome to the Puppet Module of the Week! This is a brand new blog series where we pick a module on the Puppet Forge and review it. We’ll cover a wide variety of modules in these reviews. When we run across a great module that could use some work, we’ll highlight those areas and even issue pull requests to fix them.

The goal is to provide real world feedback and solutions that will help aid the community in producing high quality modules for the Forge. This week we will be covering an nginx module authored by Benoit Cattie. It’s important to keep in mind that this is not the only nginx module on the Forge. Also, notice that the full name of this module is BenoitCattie/nginx—"BenoitCattie" is the author, and nginx is the name of the module. The idea behind the author prefix is to allow multiple modules of the same name to exist on the Forge. There are so many ways to manage and configure a service such as nginx, it would be nearly impossible for a single module to cover all the possible use cases.

There are some drawbacks to this system. Which nginx module should you use? There are a number of ways to vet modules, but the most effective way right now is to try them out and see which one works best for your environment. There are plans to aid the decision making process by providing download counts and possibly a rating system on the Forge.

With the background bits out of the way, lets get on with the review.

Purpose	Manage nginx configuration and fcgi vhosts
Module	BenoitCattie/nginx
Puppet Version	2.6+
Platforms	Debian 5, 6

The nginx module authored by Benoit Cattie provides some basic support for managing nginx configuration using Puppet, and seems to work well on the Debian based systems used for this review. Unfortunately the module documentation does not indicate support for addition platforms so your mileage may vary. Now that I think about it, we should add a "supported platforms" field to the module metadata.

Resource Overview

This nginx module manages the following resources:

Files	`/etc/nginx/nginx.conf`
Directories	`/etc/nginx/conf.d` `/etc/nginx/includes` `/etc/nginx/ssl`
Packages	`/nginx`
Services	`nginx`
Defined types	`/nginx::config` `/nginx::site` `/nginx::site_include`

Installing the module

Complexity	Easy
Installation Time	2 minutes

Installing BenoitCattie’s nginx module is as simple as using the puppet module tool (available as a rubygem/on github; and coming soon in Puppet and Puppet Enterprise):

$ puppet config print modulepath
/etc/puppet/modules:/usr/share/puppet/modules

$ cd /etc/puppet/modules
$ puppet-module install BenoitCattie/nginx

If you run into the following error:

Could not parse filename to obtain the username, module name and version.  (BenoitCattie-nginx-0.2)

You can install the nginx module manually:

$ cd /etc/puppet/modules
$ wget http://forge.puppetlabs.com/system/releases/B/BenoitCattie/BenoitCattie-nginx-0.2.tar.gz
$ tar -xvf BenoitCattie-nginx-0.2.tar.gz
$ mv BenoitCattie-nginx-0.2 nginx
$ rm BenoitCattie-nginx-0.2.tar.gz

You should now have a nginx directory in your module path.

Testing the module

At this stage I would normally run tests for the module, but it turns out that this module does not include any. Please see the previous post on checking syntax and writing tests for more info on the subject. Even without tests, we can still validate the syntax of the Puppet manifests with the 'puppet parser' command:

$ pwd
/etc/puppet/modules/nginx
$ puppet parser validate manifests/*.pp
$ echo $?
0

Looks like there are no Puppet syntax errors, and just for kicks lets see what puppet-lint (which checks your code against the Puppet Labs style guide) has to say:

$ find manifests/ -name *.pp -exec puppet-lint {} ;
WARNING: line has more than 80 characters on line 35
WARNING: line has more than 80 characters on line 37
WARNING: line has more than 80 characters on line 9
WARNING: line has more than 80 characters on line 9
WARNING: line has more than 80 characters on line 11
WARNING: line has more than 80 characters on line 13
WARNING: line has more than 80 characters on line 16
WARNING: line has more than 80 characters on line 60
WARNING: line has more than 80 characters on line 62
WARNING: line has more than 80 characters on line 63
WARNING: line has more than 80 characters on line 64
WARNING: line has more than 80 characters on line 3
WARNING: line has more than 80 characters on line 20

Not too bad, just a few lines longer than 80 characters.

Configuring the module

Complexity	Easy
Installation Time	5 minutes

This module exposes three (3) configuration parameters with what I consider sane defaults. Exposing parameters this way is a good convention to follow. I’m not forced to provide anything, it just works.

Parameters	Default value	Source
$nginx_user	www-data	ENC, node definition
$nginx_worker_processes	1	ENC, node definition
$nginx_worker_connections	1024	ENC, node definition

Each parameter can be specified via a node definition or through top scope variables if you are using an external node classifier such as the PE console.

Example usage

If you only want to manage the basics of your nginx setup, you can make use of this module by simply using a node definition.

$ cat /etc/puppet/manifest/site.pp
…
node 'agent.puppetlabs.com' {
  $nginx_user = 'www-data'
  $nginx_worker_processes = 2
  $nginx_worker_connections = 1024
  include nginx
}
…

Then on the agent we issue a Puppet run:

$ puppet agent -t
…

At this point we have nginx up and running using a rather simple configuration file, but let's take things a step further. Remember, this module also provides three defined types which we can use in our own manifest. In the next example we will use the nginx::config type to include our own nginx configuration file. With a simple declaration and an erb template our nginx config ends up in the right place and the nginx service is automatically reloaded. Can you say “Puppet Power”? Create our own module to manage a nginx vhost:

$ cat /etc/puppet/modules/myvhost
class myvhost {
  include nginx

  nginx::config { 'myvhost'
    ensure => present
  }
}

Create a nginx configuration file template:

$ cat /etc/puppet/templates/nginx/myvhost.conf.erb
# lots of nginx configuration
…

Update our node definition:

$ cat /etc/puppet/manifest/site.pp
…
node 'agent.puppetlabs.com' {
  $nginx_user = 'www-data'
  $nginx_worker_processes = 2
  $nginx_worker_connections = 1024
  include myvhost
}
…

Kick off a puppet run:

$ puppet agent -t
...
info: Caching catalog for agent.puppetlabs.com
info: Applying configuration version '1328804210'
notice: /Stage[main]/Mysite/Nginx::Config[myvhost]/File[/etc/nginx/conf.d/500-myvhost.conf]/ensure: created
info: /Stage[main]/Mysite/Nginx::Config[myvhost]/File[/etc/nginx/conf.d/500-myvhost.conf]: Scheduling refresh of Exec[reload-nginx]
notice: /Stage[main]/Nginx/Exec[reload-nginx]: Triggered 'refresh' from 1 events
notice: Finished catalog run in 0.28 seconds

Conclusion

The nginx module by Benoit Cattie can be used to manage the key parts of your nginx setup. Overall I would say this is a pretty good module. I’ll end this review with some suggestions that would make this module even better.

Update the module documentation to include supported platforms.
Use a Modulefile so that the module tool works
Follow the Puppet Labs style guide

To help address the style guide issues and missing Modulefile, I’ve issued the following pull requests, which the now-famous Benoit Cattie merged in:

Hopefully we will see a new release of the BenoitCattie/nginx module on the Forge soon. Until next time, keep writing modules and adding them to the Puppet Forge! Additional Resources