Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 38 ยท Projects and Practice

Project: A Complete Web Server Stack

Build a full Puppet design for a web server stack: control repo layout, base and web profiles, Hiera data per environment, an EPP vhost template, tests and a rollout plan.

In this project you design a small but realistic Puppet codebase from scratch: three web servers behind a load balancer, a shared base configuration, per-environment data and a safe rollout. You will use almost everything from the course: roles and profiles, Hiera, EPP templates, facts, tests and the control repo workflow.

No Puppet server runs on this site, so you build the files on your own machine (or a lab of two virtual machines) and read the commands as a recipe. The runnable blocks are JavaScript stand-ins that check parts of your design: the template output and the Hiera resolution. Never fabricate output when you run the real commands: copy what your terminal prints.

Requirements

  • Environments: production and staging.
  • Every server gets a base profile: time sync, a deploy user and a motd.
  • Web servers run nginx and serve one or more sites with a template-generated virtual host.
  • The listening port, site names and worker count come from data. Workers default to the number of CPUs.
  • The load balancer is generated from the list of web nodes, later.

Step 1: the control repo skeleton

TEXT
control-repo/
  Puppetfile
  environment.conf
  hiera.yaml
  data/
    common.yaml
    environments/production.yaml
    environments/staging.yaml
    nodes/
  manifests/site.pp
  site-modules/
    role/manifests/web.pp
    profile/manifests/base.pp
    profile/manifests/nginx.pp
    profile/templates/vhost.conf.epp
    profile/spec/classes/nginx_spec.rb

Puppetfile pins the component modules you need:

Ruby
forge 'https://forgeapi.puppet.com'
mod 'puppetlabs-stdlib', '9.4.1'
mod 'puppetlabs-ntp', '10.1.0'

site.pp stays tiny and reads the role from data (see Node Classification):

PUPPET
lookup('classes', Array[String], 'unique', ['role::minimal']).include

Step 2: the profiles

PUPPET
# site-modules/profile/manifests/base.pp
class profile::base (
  String $deploy_user = 'deploy',
) {
  include ntp

  user { $deploy_user:
    ensure     => present,
    shell      => '/bin/bash',
    managehome => true,
  }

  file { '/etc/motd':
    ensure  => file,
    content => epp('profile/motd.epp', {
      'fqdn' => $facts['networking']['fqdn'],
      'env'  => $facts['server_facts']['environment'],
    }),
  }
}
PUPPET
# site-modules/profile/manifests/nginx.pp
class profile::nginx (
  Integer                      $port    = 80,
  Hash[String, Hash]           $sites   = {},
  Optional[Integer]            $workers = undef,
) {
  $worker_count = pick($workers, $facts['processors']['count'])

  package { 'nginx':
    ensure => installed,
  }

  file { '/etc/nginx/nginx.conf':
    ensure  => file,
    content => epp('profile/nginx.conf.epp', { 'workers' => $worker_count }),
    require => Package['nginx'],
    notify  => Service['nginx'],
  }

  $sites.each |$name, $settings| {
    file { "/etc/nginx/conf.d/${name}.conf":
      ensure  => file,
      content => epp('profile/vhost.conf.epp', {
        'server_name' => $name,
        'port'        => $port,
        'docroot'     => pick($settings['docroot'], "/var/www/${name}"),
      }),
      require => Package['nginx'],
      notify  => Service['nginx'],
    }
  }

  service { 'nginx':
    ensure => running,
    enable => true,
  }
}

The role stays minimal:

PUPPET
class role::web {
  include profile::base
  include profile::nginx
}

Step 3: templates and data

TEXT
<%- | String $server_name, Integer $port, String $docroot | -%>
# Managed by Puppet
server {
  listen <%= $port %>;
  server_name <%= $server_name %>;
  root <%= $docroot %>;
}
YAML
# data/common.yaml
classes:
  - role::web
profile::nginx::port: 80
profile::nginx::sites:
  shop.example.com: {}
  api.example.com:
    docroot: /srv/api/public
YAML
# data/environments/staging.yaml
profile::nginx::port: 8080
profile::nginx::workers: 1

With the hierarchy from the Hiera lesson, staging overrides port and worker count while sharing everything else.

Step 4: stand-in checks

Before touching a server, check your design with small tools. The first stand-in renders the vhost template for each site from the data above, the second resolves the effective settings for each environment.

JS Stand-in: render the vhost for every site

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Stand-in: effective settings per environment

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Step 5: tests

Write two unit tests (see RSpec-puppet) before the first deploy:

Ruby
describe 'role::web' do
  on_supported_os.each do |os, os_facts|
    context "on #{os}" do
      let(:facts) { os_facts }
      it { is_expected.to compile.with_all_deps }
    end
  end
end

describe 'profile::nginx' do
  let(:facts) { { processors: { count: 4 } } }
  let(:params) { { sites: { 'shop.example.com' => {} } } }
  it { is_expected.to contain_file('/etc/nginx/conf.d/shop.example.com.conf').that_notifies('Service[nginx]') }
  it { is_expected.to contain_file('/etc/nginx/nginx.conf').with_content(%r{worker_processes\s+4;}) }
end

Run pdk validate and pdk test unit locally, and in CI on every pull request.

Step 6: rollout

  1. Push a branch feature_web_stack; deploy it with r10k.
  2. Point one new staging VM at that environment and run puppet agent --test --noop, then without --noop.
  3. Run the agent a second time: it must report no changes (idempotence).
  4. Check the result: curl -I http://stg1:8080 (a read-only check on your own VM).
  5. Merge to main and promote to production one node at a time, confirming with a noop run first.

Extensions to try

  • Add a profile::firewall that opens only the web port.
  • Generate a load balancer config from puppetdb_query() over web nodes (PuppetDB).
  • Add a Litmus acceptance test (Acceptance Testing).
  • Write a Bolt plan for a rolling nginx restart (Bolt).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where should the staging-specific port 8080 live?

    Environment differences are data; the profile stays the same for every environment.
  2. 2. Why do the nginx.conf and vhost files notify Service['nginx']?

    notify links a change in the file to a refresh of the service.
  3. 3. What does pick($workers, $facts['processors']['count']) do?

    pick returns the first value that is not undef or empty.
  4. 4. What is the final check of the rollout before production?

    A second run with zero changes demonstrates idempotence.

Summary

  • The project combines a control repo, base and nginx profiles, one role and Hiera data per environment.
  • Differences between environments are data; code stays identical.
  • Unit-test every role on every supported OS, and every profile's key resources and relationships.
  • Roll out through a branch, a staging node, noop, a second run and then production.

Next: Project: A Security Baseline