Vagrant

Vagrant creates local virtual machines from declarative configuration. Pigsty requires Linux. You can use Vagrant to create local Linux virtual machines for testing.

The recommended and validated versions are:

• Rocky Linux 9.8 / 10.2.
• Debian 12.15 / 13.6.
• Ubuntu 22.04.5 / 24.04.4 / 26.04.0. Major-version aliases select pinned box versions.

Quick Start

Install Dependencies

Install Vagrant and a virtual machine provider, such as VirtualBox or libvirt. On macOS, you can install the dependencies with Homebrew:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install vagrant virtualbox ansible

On Linux, use VirtualBox or vagrant-libvirt as the virtual machine provider.

Create Virtual Machines

Use the supplied make shortcuts to create virtual machines:

cd ~/pigsty/vagrant

make meta       # 1 node devbox for quick start, development, and testing
make full       # 4 node sandbox for HA testing and feature demonstration
make simu       # 20 node simubox for production environment simulation

# Other less common specs
make dual       # 2 node environment
make trio       # 3 node environment
make deci       # 10 node environment

To select a different operating system image, use a variant alias:

make meta9      # Create single node with Rocky Linux 9.8
make full12     # Create 4-node sandbox with Debian 12.15
make simu24     # Create 20-node simubox with Ubuntu 24.04.4
make full26     # Create 4-node sandbox with Ubuntu 26.04.0

These operating system suffixes are available:

• 8: EL8; 9: EL9; 10: EL10.
• 12: Debian 12.15; 13: Debian 13.6.
• 22: Ubuntu 22.04.5; 24: Ubuntu 24.04.4; 26: Ubuntu 26.04.0.

Build Environment

Use these aliases to create Pigsty build environments. These templates retain the base image:

make oss        # 7 node OSS build environment
make pro        # 7 node PRO build environment
make rpm        # 2 node EL9/10 build environment
make deb        # 5 node Debian12/13 Ubuntu22/24/26 build environment
make all        # 7 node full build environment

Spec Templates

The vagrant/spec/ directory contains predefined virtual machine specifications:

Each specification has a Specs variable that defines its nodes. For example, full.rb defines the 4-node sandbox shown below.

The current templates give every virtual machine a 32 GB primary system disk. Regular nodes also receive one data disk. Its size comes from the specification’s disk value, with a default of 128 GB if omitted.

Nodes with names that start with minio receive four 32 GB data disks instead. These disks mount at /data1 through /data4.

The disk configuration requires the experimental Vagrant disks feature. The repository Makefile automatically exports VAGRANT_EXPERIMENTAL=disks. If you run vagrant directly, set this environment variable yourself.

# full: pigsty full-featured 4-node sandbox for HA-testing & tutorial & practices

Specs = [
  { "name" => "meta"   , "ip" => "10.10.10.10" ,  "cpu" => "2" ,  "mem" => "4096" ,  "image" => "cloud-image/ubuntu-24.04" },
  { "name" => "node-1" , "ip" => "10.10.10.11" ,  "cpu" => "1" ,  "mem" => "2048" ,  "image" => "cloud-image/ubuntu-24.04" },
  { "name" => "node-2" , "ip" => "10.10.10.12" ,  "cpu" => "1" ,  "mem" => "2048" ,  "image" => "cloud-image/ubuntu-24.04" },
  { "name" => "node-3" , "ip" => "10.10.10.13" ,  "cpu" => "1" ,  "mem" => "2048" ,  "image" => "cloud-image/ubuntu-24.04" },
]

simu Spec Details

The simu.rb specification defines a 20-node production simulation:

• 3 infrastructure nodes (meta1-3): 4c16g each.
• 2 HAProxy nodes (proxy1-2): 1c2g each.
• 4 MINIO nodes (minio1-4): 1c2g each.
• 5 ETCD nodes (etcd1-5): 1c2g each.
• 6 PostgreSQL nodes (pg-src-1-3, pg-dst-1-3): 2c4g each.

Config Script

Use vagrant/config to generate the Vagrantfile from a specification and options:

cd ~/pigsty/vagrant
vagrant/config [spec] [image] [scale] [provider]

# Examples
vagrant/config meta u24            # Use 1-node spec with Ubuntu 24.04.4 image
vagrant/config dual el9            # Use 2-node spec with RockyLinux 9.7 image
vagrant/config trio d12 2          # Use 3-node spec with Debian 12.14, double resources
vagrant/config full u22 4          # Use 4-node spec with Ubuntu 22.04.5, 4x resources
vagrant/config simu u26 1 libvirt  # Use 20-node spec with Ubuntu 26.04.0, libvirt provider

Image Aliases

The configuration script supports these image aliases:

The mapping still contains the historical d11/debian11/deb11 and u20/ubuntu20/ubuntu2004 aliases. The current script explicitly rejects these aliases. They are not supported images.

Resource Scaling

Set VM_SCALE to change the resource multiplier. The default value is 1:

VM_SCALE=2 vagrant/config meta     # Double the CPU/memory resources for meta spec

For example, VM_SCALE=4 changes the meta specification from 2c4g to 8c16g:

Specs = [
  { "name" => "meta" , "ip" => "10.10.10.10", "cpu" => "8" , "mem" => "16384" , "image" => "cloud-image/ubuntu-24.04" },
]

VM Management

The vagrant/Makefile supplies shortcuts to manage virtual machines. Run these commands from the vagrant/ directory:

cd ~/pigsty/vagrant
make           # Equivalent to make start
make new       # Destroy existing VMs and create new ones
make ssh       # Write VM SSH config to ~/.ssh/ (must run after creation)
make dns       # Write VM DNS records to /etc/hosts (optional)
make start     # Start VMs and configure SSH (up + ssh)
make up        # Start VMs with vagrant up
make halt      # Shutdown VMs (alias: down, dw)
make clean     # Destroy VMs (alias: del, destroy)
make status    # Show VM status (alias: st)
make pause     # Pause VMs (alias: suspend)
make resume    # Resume VMs
make nuke      # Destroy all VMs and volumes with virsh (libvirt only)
make info      # Show libvirt info (VMs, networks, storage volumes)

SSH Keys

By default, the templates use ~/.ssh/id_rsa[.pub] as the virtual machine SSH key pair. Before deployment, make sure that this key pair exists and is valid. If necessary, generate it:

ssh-keygen -t rsa -b 2048 -N '' -f ~/.ssh/id_rsa -q

Supported Images

EL, Debian, Ubuntu, and AlmaLinux templates use cloud-image/* boxes from Vagrant Cloud. Explicit RHEL and Oracle Linux aliases use generic/* boxes.

The script uses the same cloud-image/* mapping for VirtualBox and libvirt on amd64 and arm64. Vagrant Cloud resolves actual payload availability at runtime. The vagrant/config script writes these validated versions for each supported image to make environments repeatable:

The retained Debian 11 alias pins version 20260618.2513.0. The retained Ubuntu 20.04 alias pins version 20250624.0.0. Both aliases remain unsupported.

Experimental generic/* images for RHEL, Oracle Linux, and CentOS 7 pin the final 4.3.12 release. These legacy images are outside the current support matrix.

Environment Variables

Use these environment variables to control Vagrant:

export VM_SPEC='meta'              # Spec name
export VM_IMAGE='cloud-image/rocky-9' # Image name
export VM_SCALE='1'                # Resource scaling multiplier
export VM_PROVIDER='virtualbox'    # Virtualization provider
export VAGRANT_EXPERIMENTAL=disks  # Enable disks for direct vagrant use; Makefile sets this automatically

Notes

echo "* 10.0.0.0/8" | sudo tee -a /etc/vbox/networks.conf