Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Sandbox - Linux VMs

This is an opionated repo that can be used to provision a fleet of VMs on a linux host machine using libvirt.

  • Step 1 : Make sure that the Linux host has been setup as defined SETUP.md
    • You might want to run the doctor script to check if the host and the environment variables have been set up properly.
  • Step 2 : Use the Lifecycle scripts to create and manage the virtual machines

Requirements on the host machine

The linux host machine should have various software and environment (system level) setup for the repo to work

Environment (Host machine - System level)

  • Libvirt related setup : SETUP.md
  • Cockpit for web based gui

Environment variables (Host machine - System level)

  • Libvirt should be setup in a way that the following directories should be setup as storage pools
export SANDBOX_HOME="${SANDBOX_HOME:-$HOME/projects}"
export LIBVIRT_HOME="${STORAGE_POOL_HOME:-$SANDBOX_HOME/libvirt}"
export STORAGE_POOL_IMAGES="${LIBVIRT_HOME}/images"
export STORAGE_POOL_ISOS="${LIBVIRT_HOME}/isos"
export STORAGE_POOL_DISKS="${LIBVIRT_HOME}/disks"
export STORAGE_POOL_SNAPSHOTS="${LIBVIRT_HOME}/snapshots"
export STORAGE_POOL_CLOUD_INIT_ISOS="${LIBVIRT_HOME}/cloud-init"
export DEFAULT_CLOUD_IMG="noble-server-cloudimg-amd64"

Storage pools

- `images/` → pool `default` — read-only golden cloud `.img` files. Never modify the base image directly; VMs are qcow2 overlays.
- `isos/` → pool `iso-pool` — reserved for installer ISOs, currently unused (cloud-image flow only).
- `disks/` → pool `disk-pool` — flat, per-VM `<vmname>.qcow2` + `<vmname>.state.yaml`.
- `snapshots/` → pool `snapshot-pool` — reserved for *external* snapshots; currently unused (internal qcow2 snapshots were chosen instead — don't build external-snapshot logic without revisiting this decision).
- `cloud-init/` → pool `cloudinit-pool` — generated seed ISOs `<vmname>-seed.iso`.

Each VM would have a yaml file that would contain details of the VM. The same yaml files are used to check if there is already existing VM with the same name (during initialisation). The libvirt folder on the host would look broadly something like the following :-

├── libvirt
│   ├── cloud-init
│   │   ├── vir-testing-001-seed.iso
│   │   └── vir-testing-002-seed.iso
│   ├── disks
│   │   ├── vir-testing-001.qcow2
│   │   ├── vir-testing-001.state.yaml
│   │   ├── vir-testing-002.qcow2
│   │   └── vir-testing-002.state.yaml
│   ├── images
│   │   └── noble-server-cloudimg-amd64.img
│   ├── isos
│   └── snapshots

Requirements for the repo

  • Copy env.sample to .env in the repo root and uncomment/edit whatever you want to override: cp env.sample .env
  • Environment variables are resolved with the following precedence, lowest to highest:
    1. System-level environment variables (see above)
    2. .env in the repo root, if present -- overrides #1
    3. Parameters passed to a script (e.g. --ram on 00_init_vm.sh), or the value entered at a prompt in -i/--interactive mode -- overrides both #1 and #2
  • .env is gitignored, so host- or checkout-specific overrides never get committed
  • scripts/lib/common.sh loads .env automatically (every script sources common.sh); nothing else to run

Scripts

  • Two tiers: VM/fleet scripts (create, run, and manage individual VMs or the whole fleet) and host-administration scripts (set up and manage the Linux host itself). See lifecycle_vms.md and lifecycle_host.md for the full contract of each script. Every VM-tier script (and 84 in the host tier) also accepts -h/--help for its own flag reference.
  • All scripts live in scripts/ and are run from the repo root (e.g. ./scripts/00_init_vm.sh myvm). Shared helpers for the VM tier are in scripts/lib/common.sh.
  • Scripts that support both a fire-and-forget mode and a prompted/confirmed mode take a single -i/--interactive flag rather than being split into separate files -- see below.

Sandbox Lifecycle Scripts (Summary)

# For a paricular VM 
- `scripts/00_init_vm.sh <vmname> [-i|--interactive] [options]`
    # Without -i: flag/env-driven -- RAM, CPU, disk size etc. all have defaults, override with flags
    # With -i: prompts for any field not passed as a flag, showing the resolved default
- `scripts/01_start_vm.sh`             # Starts the VM 
- `scripts/02_stop_vm.sh`
- `scripts/03_reboot_vm.sh`
- `scripts/04_destroy_vm.sh`
- `scripts/05_status_vm.sh`            # Gives the status and info 
- `scripts/06_doctor_vm.sh <vmname>`   # Per-VM diagnostics: libvirt/state consistency + guest Tailscale/UFW/Docker/cloud-init
- `scripts/11_configure_vm.sh <vmname> [-i|--interactive] [options]`  # Docker, Tailscale, UFW
    # Without -i: fire-and-forget -- runs every step unconditionally, no prompts
    # With -i: confirms before each step, streams output live
- `scripts/12_resize_vm.sh <vmname> [-i|--interactive] [options]`     # CPUs, RAM, disk, autostart
    # Without -i: only the fields you pass change, no prompts
    # With -i: shows current config, prompts for any field not passed as a flag, confirms once
- Snapshots (not yet built, see PLAN.md Phase 6)
    - `scripts/21_snapshot_vm.sh`
    - `scripts/22_restore_vm.sh`

# Testing setups 
- `scripts/09_doctor_host.sh`          # Host-level diagnostic tests
- `scripts/08_test.sh`                 # End-to-end smoke test: doctor -> init -> lifecycle -> destroy, against ephemeral test VMs

# Managing multiple VMs (Managing the fleet)
- `scripts/50_list_vms.sh`             # Will list all the vms and their statuses
- `scripts/51_info_vms.sh`             # Dumps full state.yaml detail for every VM (no vmname arg) 

Host Administration Scripts (Summary)

Set up and manage the Linux host itself, not any individual VM -- see lifecycle_host.md for the full contract, including a "Common Usage Patterns" section. Numbered 80+, no vmname arg, most require sudo (unlike the VM-tier scripts above).

- `scripts/80_host_check_specs.sh`                         # Read-only: KVM support, CPU/RAM/disk/network specs
- `scripts/81_host_setup_initial_dependencies.sh`          # Installs packages, yq, joins libvirt/kvm groups
- `scripts/82_host_setup_bootstrap_script.sh`               # Installs /etc/profile.d/sandbox.sh
- `scripts/83_host_configure_libvirt_storage_pools.sh`      # Defines/starts the 5 libvirt storage pools (idempotent)
- `scripts/84_host_change_libvirt_storage_pools.sh <path>`  # Moves LIBVIRT_HOME + all managed VMs to a new location
- `scripts/85_host_check_libvirt_config.sh`                 # Read-only: env vars, tool versions, pool/net/domain list

Notes

  • Naming convention of virtual machines : vir-ubuntu-01 and then additional numbers. The name should always suggest that it is a virtual machine

References

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages