Puppetlabs-Apache: Puppet Enterprise Supported Module

With the launch of Puppet Enterprise 3.2, we've introduced Puppet Enterprise supported modules. One of the first modules to be supported is puppetlabs-apache.

What this means for you, the sysadmin, is that you’ll be able to expect consistency from the puppetlabs-apache module. If you’re a Puppet Enterprise customer, you’ll be able to receive technical support for the module through the usual channels, as well as a guarantee that the latest supported version of the module works with Puppet Enterprise 3.2. You can also expect continuing development on this and the other Puppet Enterprise supported modules: feature additions, plus bug fixes and security patches as needed.

Our Apache module allows you to configure and manage the Apache HTTP server in a simple and straightforward manner, creating vhosts, and other configuration, without much effort. Managing Apache (or, for the stickler, httpd) is a fairly common use case for our users, so we’re excited to be offering this functionality to you.

For the purposes of this post, we’ve got two nodes: the all-in-one Puppet Enterprise master, master.puppetlabs.com, and a webserver node, webserver.puppetlabs.com. Both are running CentOS 6.5.

Basic use of the module is fairly trivial. You can install it on your master, using the Puppet module tool, like so:

[root@master ~]# puppet module install puppetlabs-apache  
Notice: Preparing to install into /etc/puppetlabs/puppet/modules ...
Notice: Downloading from https://forgeapi.puppetlabs.com ...
Notice: Installing -- do not interrupt ...
/etc/puppetlabs/puppet/modules
└─┬ puppetlabs-apache (v1.0.1)
  ├── puppetlabs-concat (v1.0.0) [/opt/puppet/share/puppet/modules]
  └── puppetlabs-stdlib (v3.2.0) [/opt/puppet/share/puppet/modules]

Basic Setup

A quick node definition gets us Apache httpd installed, along with a vhost configured to serve a basic webpage.

node 'webserver.puppetlabs.com' {
  class { 'apache': }  
  apache::vhost { 'webserver.puppetlabs.com':
    port    => '80',
    docroot => '/var/www/webserver'  
  }
}

Just like that, we’ve got a basic website setup:

A basic website setup

However, there’s a problem!

[root@webserver modules]# apachectl -t -D DUMP_MODULES | wc -l 
Syntax OK 
44    

That’s a ton of modules, and you probably don’t want all of them configured in your production environment.

Enabling Specific Modules

We can fix that by setting default_mods to false, and including the classes for the modules we want to load:

node 'webserver.puppetlabs.com' {  
  class { 'apache':
    default_mods => false,  
  }  
  include apache::mod::php  
  apache::vhost { 'webserver.puppetlabs.com':    
    port    => '80',    
    docroot => '/var/www/webserver'  
  }
}

Now we’re able to load a PHP site that displays phpinfo():

The module’s README file contains a list of modules which have built-in classes, and other arbitrary modules can be installed via the apache::mod { 'foo': } defined type, where foo is the name of the module you’d like to enable.

Generally the puppetlabs-apache module can install and enable any httpd module included in your distro’s repositories, but it doesn’t know about all of them. If you need to enable a module that puppetlabs-apache doesn’t know about, you’ll need to distribute it to your servers before the apache::mod defined type can enable it for you successfully.

Adding SSL to Your Site

The puppetlabs-apache module makes adding SSL to your site easy.

Adding ssl => true and changing port from 80 to 443 is sufficient to get your site up with a self-signed cert, which will be automatically generated. Assuming you want to add a valid certificate from a trusted certificate authority, it’s as easy as:

apache::vhost { 'webserver.puppetlabs.com':  
  port     => '443',  
  docroot  => '/var/www/webserver',  
  ssl      => true,  
  ssl_cert => '/etc/pki/tls/certs/localhost.crt',  
  ssl_key  => '/etc/pki/tls/private/localhost.key',
}

For those of you using GoDaddy and other certificate providers that require intermediate certificates, you can specify an intermediate certificate using the ssl_chain parameter.

A More Complex Example

Those examples all demonstrate how you can do some fairly basic Apache HTTPD configuration, but what about a more complex case?

What about configuring a site that redirects all HTTP traffic to HTTPS, with a custom SSL certificate, and redirects all Windows users to bing.com? Easy!

node 'webserver.puppetlabs.com' {  
  class { 'apache':    
    default_mods => false, 
  }  

  include apache::mod::php  
  include apache::mod::ssl  
  include apache::mod::rewrite  

  apache::vhost { 'webserver.puppetlabs.com-http':    
    servername      => 'webserver.puppetlabs.com',    
    port            => '80',    
    docroot         => '/var/www/webserver',    
    redirect_status => 'permanent',    
    redirect_dest   => 'https://webserver.puppetlabs.com/',  
  }  

  apache::vhost { 'webserver.puppetlabs.com-https':    
    servername      => 'webserver.puppetlabs.com',    
    port            => '443',    
    docroot         => '/var/www/webserver',    
    ssl             => true,    
    ssl_cert        => '/etc/pki/tls/certs/localhost.crt',  
    ssl_key         => '/etc/pki/tls/private/localhost.key',
    rewrite_cond    => '%{HTTP_USER_AGENT} Windows',    
    rewrite_rule    => '^.*$ http://bing.com/ [R=301,L]'  
  }
}

The above example generates two vhosts — one for HTTP that merely redirects all traffic to the HTTPS version of the site, and a second that serves the HTTPS version of the page. Finally, a mod_rewrite condition and rule has been added using the rewrite_cond and rewrite_rule parameters.

Moving Forward

That’s a basic introduction to using the puppetlabs-apache module to install and configure basic websites.

For more advanced configuration, including things like FastCGI and configuring Apache to act as a load balancer, check out the README tab on the Puppet Forge page for puppetlabs-apache.

Download Puppet Enterprise today for free, and find out how easy it can be to manage your Apache HTTPD web servers.

Zachary Alex Stern is a support engineer at Puppet Labs.

Learn More

Comments

Zachary Alex Stern

Zachary Alex Stern

Note: I updated this post on 3/13/2014 to reflect two missing lines of configuration in the final example.

Leave a comment