Skip to content

Version v3.7.0 of the documentation is no longer actively maintained. The site that you are currently viewing is an archived snapshot. For up-to-date documentation, see the latest version.

Vagrant

Provision local VM with vagrant

Pigsty requires Linux environment, you can easily create local linux VMs with Vagrant.

You’ll also need a virtual machine provider, (like VirtualBox for laptops and libvirt for servers)

Get Started

You can install vagrant, virtualbox, ansible on macOS with homebrew:

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

You are all set! use the make shortcuts to create VMs:

~/pigsty
make meta       # 1-node devbox for quick start, dev, test & playground
make full       # 4-node sandbox for HA-testing & feature demonstration
make simu       # 36-node simubox for production environment simulation
...
make meta9      # create singleton-meta node with bento/rockylinux-9 image
make full22     # create 4-node sandbox with generic/ubuntu2204 image
make simu12     # create 36-node simulation env with generic/debian12 image

Configuration

You have to define VMs in the Vagrantfile before launch. The default Vagrantfile defines a el9 (bento/rockylinux-9) 1-node virtual machine with the local virtualbox VM provider.

We have a list of pre-defined VM specs available in the vagrant/spec Folder

Templates Nodes Spec Comment Alias
meta.rb 1 node 2c4g x 1 Single Node Meta Devbox
dual.rb 2 node 1c2g x 2 Dual Nodes
trio.rb 3 node 1c2G x 3 Three Nodes
full.rb 4 node 2c4g + 1c2g x 3 Full-Featured 4 Node Sandbox
simu.rb 36 node misc Prod Env Simulation Simubox
oss.rb 3 node 1c2g x 3 3-Node OSS Building Env
pro.rb 5 node 1c2g x 5 5-Node PRO Building Env

Each spec file contains a Specs variable describe VM nodes. For example, the full.rb contains:

# 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" => "bento/rockylinux-9"  },
  { "name" => "node-1" , "ip" => "10.10.10.11" ,  "cpu" => "1" ,  "mem" => "2048" ,  "image" => "bento/rockylinux-9"  },
  { "name" => "node-2" , "ip" => "10.10.10.12" ,  "cpu" => "1" ,  "mem" => "2048" ,  "image" => "bento/rockylinux-9"  },
  { "name" => "node-3" , "ip" => "10.10.10.13" ,  "cpu" => "1" ,  "mem" => "2048" ,  "image" => "bento/rockylinux-9"  },
]

You can use specs with the config script, it will render the Vagrantfile according to spec and environment variables (resouce, image, vm provider, etc…).

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

vagrant/config meta                # use the 1-node spec, default el8 image
vagrant/config dual el9            # use the 2-node spec, use el9 image instead
vagrant/config trio d12 2          # use the 3-node spec, use debian12 image, double the cpu/mem resource
vagrant/config full u22 4          # use the 4-node spec, use ubuntu22 image instead, use 4x cpu/mem resource
vagrant/config simu u24 1 libvirt  # use the 36-node spec, use ubuntu24 image instead, use libvirt as provider instead of virtualbox

You can scale the resource unit with environment variable VM_SCALE, the default value is 1.

For example, VM_SCALE=2 vagrant/config meta will double the cpu / mem resources of the meta spec

Specs = [
  { "name" => "meta" , "ip" => "10.10.10.10", "cpu" => "8" , "mem" => "16384" , "image" => "bento/rockylinux-9" },
]

Shortcuts

You can create the VMs with vagrant up command after configuration.

Pigsty templates will use your ~/.ssh/id_rsa[.pub] as the default ssh key for vagrant provisioning. Make sure you have a valid ssh key pair before you start, you can generate one by: ssh-keygen -t rsa -b 2048

There are some shortcuts that wrap the vagrant commands, you can use them to manage the VMs.

~/pigsty/vagrant
make         # = make start
make new     # destroy existing vm and create new ones
make ssh     # write VM ssh config to ~/.ssh/     (required)
make dns     # write VM DNS records to /etc/hosts (optional)
make start   # launch VMs and write ssh config    (up + ssh)
make up      # launch VMs with vagrant up
make halt    # shutdown VMs (down,dw)
make clean   # destroy VMs (clean/del/destroy)
make status  # show VM status (st)
make pause   # pause VMs (suspend,pause)
make resume  # pause VMs (resume)
make nuke    # destroy all vm & volumes with virsh (if using libvirt)

Version

Pigsty currently uses the following vagrant boxes for testing:

x86_64
$ vagrant box list

el8 :  bento/rockylinux-8     (libvirt, 202502.21.0, (amd64))
el9 :  bento/rockylinux-9     (libvirt, 202502.21.0, (amd64))

d11 :  generic/debian11       (libvirt, 4.3.12, (amd64))
d12 :  generic/debian12       (libvirt, 4.3.12, (amd64))

u20 :  generic/ubuntu2004     (libvirt, 4.3.12, (amd64))
u22 :  generic/ubuntu2204     (libvirt, 4.3.12, (amd64))
u24 :  bento/ubuntu-24.04     (libvirt, 20250316.0.0, (amd64))

Not all of them have arm64 arch support, so beware when using Apple Silicon MacOS.

aarch64
bento/rockylinux-9 (virtualbox, 202502.21.0, (arm64))
bento/ubuntu-24.04 (virtualbox, 202502.21.0, (arm64))

You can find the supported Box Image on https://app.vagrantup.com/bento/boxes

Caveat

Virtualbox Network Configuration

It require extra setup to use the default 10.x.x.x CIDR as host-only networks when using older version of virtualbox as vagrant provider: add it to /etc/vbox/networks.conf

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