Set up on Vagrant#

This guide covers how to configure Vagrant as the testbed in a Kiso experiment.

Vagrant is the local development testbed. Use it to develop and test experiments before running them on FABRIC or Chameleon. See Components — Vagrant for context on when to use Vagrant.

Prerequisites#

Vagrant installed (version 2.3 or later)
A supported VM backend:
- VirtualBox — install VirtualBox and set backend: virtualbox in the config
- libvirt (default) — install libvirt and the vagrant-libvirt plugin
Kiso installed: pip install kiso[vagrant]

Verify Vagrant is working:

vagrant --version

Vagrant-specific config fields#

sites:
  - kind: vagrant
    backend: virtualbox           # Optional — libvirt (default) or virtualbox
    box: generic/debian11         # Optional — base VM image (default: generic/debian11)
    user: root                    # Optional — SSH user (default: root)
    name_prefix: enos             # Optional — prefix for VM names (default: enos)
    config_extra: |               # Optional — extra Vagrant DSL config applied to all VMs
      config.vm.boot_timeout = 600
    resources:
      machines:
        - labels: [compute]       # Required — one or more labels
          flavour: small          # Required — see flavour table below (or use flavour_desc)
          number: 1               # Optional — number of VMs (default: 1)
          backend: virtualbox     # Optional — per-machine backend override
          box: bento/rockylinux-9 # Optional — per-machine box override
          user: root              # Optional — per-machine SSH user override
          name_prefix: myvm       # Optional — per-machine name prefix override
          config_extra_vm: |      # Optional — extra Vagrant DSL config for this VM only
            vb.memory = 2048
      networks:
        - cidr: 172.16.42.0/16    # Required
          labels: [net1]          # Required

Machine flavours#

Flavour	vCPUs	RAM
`tiny`	1	512 MB
`small`	1	1024 MB
`medium`	2	2048 MB
`big`	3	3072 MB
`large`	4	4096 MB
`extra-large`	6	6144 MB

Alternatively, use flavour_desc to specify a custom resource profile:

machines:
  - labels: [compute]
    flavour_desc:
      core: 2    # Required — number of vCPUs
      mem: 4096  # Required — RAM in MB

Minimal working example#

name: vagrant-test

sites:
  - kind: vagrant
    resources:
      machines:
        - labels: [compute]
          flavour: small
          number: 1
      networks:
        - cidr: 172.16.42.0/16
          labels: [net1]

experiments:
  - kind: shell
    name: check
    scripts:
      - labels: [compute]
        script: hostname

Run it:

kiso up experiment.yml
kiso run experiment.yml
kiso down experiment.yml

Verifying the setup#

After kiso up, verify the VM is running:

vagrant status

You should see the provisioned VM(s) in the running state.

You can also connect to a node directly using kiso ssh with the label assigned to it in your config:

kiso ssh <your-node-label>

Common failure modes#

Invalid VM architecture

You are using a Box that is not built to support that architecture of the machine running Kiso.

Stderr: VBoxManage: error: Cannot run the machine because its platform architecture x86 is not supported on ARM

Port conflicts

If another Vagrant VM is running on the same host using the same private network CIDR, kiso up may fail. Stop other VMs first or use a different CIDR.

VM stuck in “waiting for SSH”

This usually means the VM backend is not starting the VM correctly. Increasing the flavour (medium or large) can help if the VM is resource-starved.

kiso up fails partway through

Run kiso up --force experiment.yml to tear down and recreate resources from scratch.

Set up on Vagrant

Contents