Managing an Apache server with Puppet

Puppet is a configuration manager embracing the infrastructure-as-code movement. It allows you to describe the desired configuration of your system. One of the most common tasks for Puppet is to configure an Apache frontend.

This blog post explains how you can use Puppet to configure an Apache server as frontend using the mod_proxy, without having to write a single Apache directive.

1 machine -> n servers

We often have the following topology: we use the same machine to host several systems. Let’s take, for example, a server used as a development forge and so hosting a maven repository manager, a continuous integration server, a code browser, a quality tracker, a source repository manager and so on. Another example is to host several web sites on the same machine. This is quite a common configuration for web sites that do not consume a lot of resources.

To route the request to the right web site, we set up an Apache frontend (aka proxy) redirecting the requests to the correct web site. The redirection is based on the target url, so for example redirects to http://localhost:9015, or http://mydomain/nexus to http://localhost:9000.

An Apache server used as frontend
An Apache server used as frontend

Configuring the Apache server to delegate the requests is not hard, once you have the required modules (mods) enabled, and are able to write Apache virtual host configurations (a mix between XML and plain text). But it starts to become rather cumbersome when the number of proxied sites or servers starts to grow, or when you need to replicate this configuration on another server.

By using Puppet for this purpose, we simplify the deployment of the system. Adding a web site will require 5 lines of code only. So in addition to all the other advantages of using Puppet and infrastructure-as-code, it also makes your Apache configuration cleaner.

Using Puppet to configure virtual hosts

There are a lot of Puppet modules to configure Apache. We chose one provided by puppetlabs, available on github. This module supports mod_proxy and mod_redirect out of the box.

So the first thing to do is to install the module. This module is hosted on the Puppet Module Forge, so can be installed using the puppet-module command:

puppet-module install puppetlabs-apache

Now that we have the module, we need to describe our system. With Puppet, you describe the resulting state and not how you reach it. So in our case we need to:

  • ensure that Apache is available,
  • ensure that the mod_proxy is enabled,
  • define our virtual hosts

We can achieve these tasks with the following Puppet manifest:

Exec {
    path => ["/bin", "/sbin", "/usr/bin", "/usr/sbin"],

include apache

a2mod { "Enable proxy mod":
	name => "proxy",
	ensure => "present"

a2mod { "Enable proxy_http mod":
	name => "proxy_http",
	ensure => "present"

apache::vhost::proxy { "my-site":
	servername => "",
	port => 80,
	dest => "http://localhost:9015",
	vhost_name => "my-site"

So, this manifest checks whether Apache 2 is installed and running correctly. Then, it ensures that the Proxy module and the Proxy module for HTTP are enabled. Finally, we declare our proxied site. The server name and the port indicates the address received by the Apache server that need to be redirected to the dest parameter. So in the previous example, we redirect to http://location:9015.

Of course, we can declare several such proxied sites:

apache::vhost::proxy { "my-site":
	servername => "",
	port => 80,
	dest => "http://localhost:9015",
	vhost_name => "my-site"

apache::vhost::proxy { "my-site-2":
	servername => "",
	port => 80,
	dest => "http://localhost:9016",
	vhost_name => "my-site-2"

When we apply this manifest, all virtual hosts are created, and the Apache server restarted. So, we’re up and running.

One of the big advantages of Puppet is that you can add a virtual host, re-apply the configuration and it will set up everything for you. However, if the host is already defined, Puppet will do nothing: only new hosts are created.


This blog post has shown how Puppet can be used to create Apache virtual hosts to manage an Apache frontend delegating on proxied servers. If you’re running topologies such as the one described in this blog post, Puppet can help you to manage such configuration in a very elegant way.

8 thoughts on “Managing an Apache server with Puppet

  1. Hi,

    Can you please tell me which os are you using? Debian I presume! I am looking at a rhel7 box and I don’t think there is a2mod in yum based systems… Please can you help me in setting up what you did here in a RedHat based environment?

  2. Hello,

    I’m very new to DevOps and Puppet in particular and I’m trying to learn it. When I run your code in my VM I always have this error :
    Error: Evaluation Error: Error while evaluating a Resource Statement, Invalid resource type apache::vhost::proxy_http at /root/kmlunch.pp:17:1 on node learning.puppetlabs.vm

    Can you please expain it to me and tell me how can I fix it? Thanks in advance,


  3. What i do not realize is in reality how you’re not actually a lot more well-appreciated than you might be right
    now. You’re so intelligent. You realize thus significantly in terms of this matter,
    made me in my view consider it from so many numerous angles.
    Its like men and women aren’t fascinated except it is something to
    do with Girl gaga! Your individual stuffs great. All the time care for it up!

  4. Hi,

    I m learning puppet and i have some question about this manifest you created. Did You create a new manifest with this config or a You edited some of the puppetlabs-apache manifests?

    I m having a hard time to make puppt config my apache.


    1. Hi Havary,

      we created a new manifest with this config, in which we use the standard puppetlabs-apache module. For beginners we can recommend the book “Pro Puppet” written by James Turnbull and Jeffry McCune. Although some parts are already outdated, it still offers a well-structured overview of what you can do with puppet. Helpful github profiles to get deeper into puppet and see some examples how to adjust existing modules and how to write complete puppet-frameworks are example42, akquinet, cescoffier and saheba. Generally, github is a good place to get to know a lot of different ways how to deal with customization of puppet modules. Hope that helps you, to select the best approach for you as well.


Comments are closed.