Module of the Week: BenoitCattie/nginx – Basic nginx configuration
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 |
$ 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 |
| 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 |
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
Share this post via:
