# Vagrant

> Provision local VM with vagrant
---

Pigsty requires Linux environment, you can easily create local linux VMs with [**Vagrant**](https://www.vagrantup.com/).

You'll also need a virtual machine provider, (like [VirtualBox](https://www.virtualbox.org/) for laptops and libvirt for servers)


--------

## Get Started

You can install vagrant, virtualbox, ansible on macOS with [**homebrew**](https://brew.sh/):

```bash {title="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:

```bash {title="~/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`](https://github.com/pgsty/pigsty/blob/v3.7.0/vagrant/Vagrantfile) before launch.
The default Vagrantfile defines a el9 ([`bento/rockylinux-9`](https://app.vagrantup.com/bento/boxes/rockylinux-9)) 1-node virtual machine with the local virtualbox VM provider.



- **`vagrant/`**
  - **`spec/`**
    - [`meta.rb`](https://github.com/pgsty/pigsty/blob/v3.7.0/vagrant/spec/meta.rb)
    - [`full.rb`](https://github.com/pgsty/pigsty/blob/v3.7.0/vagrant/spec/full.rb)
    - [`simu.rb`](https://github.com/pgsty/pigsty/blob/v3.7.0/vagrant/spec/simu.rb)
    - [`......`](https://github.com/pgsty/pigsty/tree/v3.7.0/vagrant/spec/)
  - [`Vagrantfile`](https://github.com/pgsty/pigsty/blob/v3.7.0/vagrant/Vagrantfile)

We have a list of pre-defined VM specs available in the [`vagrant/spec`](https://github.com/pgsty/pigsty/tree/v3.7.0/vagrant/spec) Folder

|                                 Templates                                 |  Nodes  |      Spec       |         Comment         |  Alias  |
|:-------------------------------------------------------------------------:|:-------:|:---------------:|:-----------------------:|:-------:|
| [meta.rb](https://github.com/pgsty/pigsty/blob/v3.7.0/vagrant/spec/meta.rb) | 1 node  |    2c4g x 1     |    Single Node Meta     | Devbox  |
| [dual.rb](https://github.com/pgsty/pigsty/blob/v3.7.0/vagrant/spec/dual.rb) | 2 node  |    1c2g x 2     |       Dual Nodes        |         |
| [trio.rb](https://github.com/pgsty/pigsty/blob/v3.7.0/vagrant/spec/trio.rb) | 3 node  |    1c2G x 3     |       Three Nodes       |         |
| [full.rb](https://github.com/pgsty/pigsty/blob/v3.7.0/vagrant/spec/full.rb) | 4 node  | 2c4g + 1c2g x 3 |  Full-Featured 4 Node   | Sandbox |
| [simu.rb](https://github.com/pgsty/pigsty/blob/v3.7.0/vagrant/spec/simu.rb) | 36 node |      misc       |   Prod Env Simulation   | Simubox |
|  [oss.rb](https://github.com/pgsty/pigsty/blob/v3.7.0/vagrant/spec/oss.rb)  | 3 node  |    1c2g x 3     | 3-Node OSS Building Env |         |
|  [pro.rb](https://github.com/pgsty/pigsty/blob/v3.7.0/vagrant/spec/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:

```ruby
# 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`](https://github.com/pgsty/pigsty/blob/v3.7.0/vagrant/config) script, it will render the `Vagrantfile` according to spec and environment variables (resouce, image, vm provider, etc...).

```bash
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

```bash
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.

```bash {title="~/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:

```bash {title="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.

```bash {title="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`

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