Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 36 ยท Projects and Practice

Project: A Three-tier Cluster

Build a multi-machine Vagrant cluster: HAProxy load balancer, two web servers and a database on a private network, generated from a YAML file with shared provisioning.

This project puts the whole chapter together. You build a small production-shaped system on your laptop: a load balancer in front of two web servers, with one database behind them. Everything is declared in files, generated by loops, and started with one command.

The Vagrantfile and scripts are read-only (they need Vagrant and VirtualBox on your computer). The Ruby stand-ins at the end generate the cluster plan and the HAProxy configuration, so you can test the generating logic here.

The design

Three tiers

lb HAProxy, port 8080
web1, web2 Nginx and the app
db PostgreSQL

All on one private network.

1 / 2

Network plan on 192.168.56.0/24:

Machine Role IP Notes
lb HAProxy 192.168.56.10 host port 8080 forwards here
web1 Nginx app 192.168.56.21
web2 Nginx app 192.168.56.22
db PostgreSQL 192.168.56.30 listens on its private address only

Step 1: describe machines as data

machines.yml:

YAML
defaults:
  box: ubuntu/jammy64
  memory: 768
  cpus: 1
machines:
  - { name: db,   role: db,  ip: 192.168.56.30, memory: 1024 }
  - { name: web1, role: web, ip: 192.168.56.21 }
  - { name: web2, role: web, ip: 192.168.56.22 }
  - { name: lb,   role: lb,  ip: 192.168.56.10, forward: { 8080: 80 } }

db comes first, then the web servers, then the load balancer, because Vagrant creates machines in order and each tier depends on the one before it. This follows the ideas from data-driven machine definitions.

Step 2: the Vagrantfile

Ruby
require "yaml"

Vagrant.require_version ">= 2.3.0"

settings = YAML.load_file(File.join(__dir__, "machines.yml"))
defaults = settings.fetch("defaults")
machines = settings.fetch("machines").map { |m| defaults.merge(m) }

hosts = machines.map { |m| "#{m['ip']} #{m['name']}" }.join("\n")
web_ips = machines.select { |m| m["role"] == "web" }.map { |m| m["ip"] }

Vagrant.configure("2") do |config|
  config.vm.synced_folder ".", "/vagrant", disabled: true

  machines.each do |spec|
    config.vm.define spec["name"] do |node|
      node.vm.box = spec["box"]
      node.vm.hostname = spec["name"]
      node.vm.network "private_network", ip: spec["ip"]

      (spec["forward"] || {}).each do |host_port, guest_port|
        node.vm.network "forwarded_port",
          guest: guest_port, host: host_port, host_ip: "127.0.0.1"
      end

      node.vm.provider "virtualbox" do |vb|
        vb.name = "cluster-#{spec['name']}"
        vb.memory = spec["memory"]
        vb.cpus = spec["cpus"]
        vb.linked_clone = true
      end

      # 1. every machine learns every name
      node.vm.provision "hosts", type: "shell", inline: <<~SH
        sed -i '/# cluster/,$d' /etc/hosts
        printf '# cluster\n%s\n' "#{hosts}" >> /etc/hosts
      SH

      # 2. role-specific setup
      node.vm.provision "role", type: "shell",
        path: "provision/#{spec['role']}.sh",
        env: { "NODE_NAME" => spec["name"], "WEB_IPS" => web_ips.join(",") }
    end
  end
end

Things to notice: the hosts file is built once in Ruby and injected into each machine, the role script is chosen by name (db.sh, web.sh, lb.sh), and the default /vagrant share is disabled so the provisioning files are passed explicitly. Using path: for the role script uploads it from the project folder, which does not need the synced folder.

Step 3: role scripts

provision/db.sh installs PostgreSQL, listens on the private address and allows the web servers:

Terminal
#!/usr/bin/env bash
set -euo pipefail
export DEBIAN_FRONTEND=noninteractive
apt-get update -qq && apt-get install -y -qq postgresql

CONF=/etc/postgresql/14/main
sed -i "s/^#\?listen_addresses.*/listen_addresses = 'localhost,192.168.56.30'/" $CONF/postgresql.conf
grep -q '192.168.56.0/24' $CONF/pg_hba.conf || \
  echo "host app app 192.168.56.0/24 scram-sha-256" >> $CONF/pg_hba.conf
systemctl restart postgresql

sudo -u postgres psql -tc "SELECT 1 FROM pg_roles WHERE rolname='app'" | grep -q 1 || \
  sudo -u postgres psql -c "CREATE ROLE app LOGIN PASSWORD 'dev-only'"
sudo -u postgres psql -tc "SELECT 1 FROM pg_database WHERE datname='app'" | grep -q 1 || \
  sudo -u postgres createdb -O app app

provision/web.sh installs Nginx and serves a page that shows which server answered, so load balancing is visible:

Terminal
#!/usr/bin/env bash
set -euo pipefail
export DEBIAN_FRONTEND=noninteractive
apt-get update -qq && apt-get install -y -qq nginx

cat > /var/www/html/index.html <<HTML
<h1>Hello from ${NODE_NAME}</h1>
HTML
systemctl enable --now nginx

provision/lb.sh installs HAProxy and writes a configuration listing the web servers from WEB_IPS:

Terminal
#!/usr/bin/env bash
set -euo pipefail
export DEBIAN_FRONTEND=noninteractive
apt-get update -qq && apt-get install -y -qq haproxy

{
  cat <<'CFG'
defaults
    mode http
    timeout connect 5s
    timeout client  30s
    timeout server  30s

frontend public
    bind *:80
    default_backend web

backend web
    balance roundrobin
CFG
  i=1
  for ip in ${WEB_IPS//,/ }; do
    echo "    server web$i $ip:80 check"
    i=$((i+1))
  done
} > /etc/haproxy/haproxy.cfg

systemctl restart haproxy

Step 4: bring it up and test

TEXT
$ vagrant up                      # creates db, web1, web2, lb in order
$ vagrant status
db    running (virtualbox)
web1  running (virtualbox)
web2  running (virtualbox)
lb    running (virtualbox)

$ for i in 1 2 3 4; do curl -s http://localhost:8080 | head -1; done
<h1>Hello from web1</h1>
<h1>Hello from web2</h1>
<h1>Hello from web1</h1>
<h1>Hello from web2</h1>

$ vagrant ssh web1 -c "nc -zv db 5432"
Connection to db (192.168.56.30) 5432 port [tcp/postgresql] succeeded!

The alternation proves round-robin balancing. Now test failure: vagrant halt web1, then run the curl loop again. HAProxy's check marks web1 as down and sends everything to web2. Bring it back with vagrant up web1 and watch it rejoin.

Useful commands during the project:

  • vagrant provision lb re-runs only the load balancer's scripts.
  • vagrant ssh lb -c "echo 'show stat' | sudo socat stdio /run/haproxy/admin.sock" reads HAProxy statistics (needs the stats socket enabled).
  • vagrant destroy -f removes the cluster; vagrant up rebuilds it identically.

Stretch goals

  1. Add web3 with one line in machines.yml and confirm the load balancer picks it up.
  2. Make the web page read a counter from PostgreSQL to prove web-to-db access.
  3. Add a trigger that dumps the database before vagrant destroy (triggers).
  4. Install vagrant-hostmanager and reach http://lb.test in your browser (plugins).
  5. Swap the shell scripts for Ansible playbooks with the ansible_local provisioner.

A stand-in: generate the plan and the HAProxy config

The most interesting logic in this project, turning data into a plan and a configuration, is plain Ruby. This program does the validation, builds the hosts file and the HAProxy backend, and prints a memory total. It does not need Vagrant.

Ruby Plan the cluster

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why is db defined before web1, web2 and lb in machines.yml?

    Definition order is creation order, so dependencies go first.
  2. 2. How does the load balancer learn the web servers' addresses in this design?

    The Vagrantfile computes the web IPs and passes them to the role script, so adding a web server needs only a new YAML entry.
  3. 3. What proves that round-robin balancing works?

    Each web page names its server, so alternating answers show balancing.
  4. 4. Which machine gets a forwarded port to the host?

    Only the load balancer is public; the rest are reachable on the private network.

Summary

  • You modelled a three-tier system as data, generated machines and hosts with Ruby, and provisioned each tier by role.
  • Only the load balancer is exposed to the host; the database listens on its private address.
  • Halting a web server tests failure handling; adding one tests how well the data-driven design scales.
  • The same ideas apply to any multi-machine environment.

Next: Practice and challenges