resf-testing-repo/README.md

Rocky Linux Testing Framework

Simple, portable Sparrowdo testing framework for Rocky Linux.

Overview

This framework provides automated testing for Rocky Linux:

• VM Isolation: Each test runs in a fresh VM
• Parallel Execution: Run multiple tests concurrently
• Fast Provisioning: Linked clones (copy-on-write) for speed
• Bootstrap Once: Golden image approach saves time

Two implementations available:

• Ansible: Provider-aware, structured roles, better for automation (recommended)
• Shell Scripts: Simple scripts, easy to integrate anywhere (libvirt only)

Prerequisites

sudo dnf install -y qemu-kvm libvirt virt-install guestfs-tools rakudo ansible
sudo systemctl enable --now libvirtd
sudo usermod -a -G libvirt $(whoami)
ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa -N ""

Quick Start

Ansible (Recommended)

cd ansible

# 1. Add your tests to vars/test-definitions.yml
# 2. Build golden image (interactive prompt for Rocky version)
ansible-playbook playbooks/libvirt/build-golden-image.yml

# 3. Run all tests
ansible-playbook playbooks/run-tests.yml

# 4. Run specific test
ansible-playbook playbooks/run-tests.yml -e "test_filter=Sparky_Knot"

Shell Scripts

# Download base image
BASE=$(./scripts/download-image.sh \
  https://download.rockylinux.org/pub/rocky/9/images/x86_64/Rocky-9-GenericCloud-Base.latest.x86_64.qcow2)

# Build golden image
./scripts/build-golden.sh "$BASE" /var/lib/libvirt/images/golden.qcow2

# Run test
./scripts/run-test.sh my-test \
  https://github.com/your-org/test-repo.git \
  /var/lib/libvirt/images/golden.qcow2

How It Works

Download QCOW2 → Build Golden Image → Run Tests → Cleanup
                 (bootstrap once)     (parallel)

Golden Image Creation:

1. Copy base QCOW2 image
2. Install Raku, Sparrowdo via virt-customize
3. Create rocky user with sudo and SSH keys
4. Boot VM and run sparrowdo --bootstrap (once)
5. Shutdown, save as golden image

Test Execution:

1. Provision VM as linked clone (~1 second)
2. Clone test repository
3. Run sparrowdo --no_sudo
4. Cleanup VM

Directory Structure

.
├── ansible/                      # Ansible implementation (provider-aware)
│   ├── inventory/
│   │   ├── hosts.yml            # Provider groups (libvirt, aws, azure)
│   │   └── group_vars/          # Provider-specific settings
│   ├── vars/
│   │   └── test-definitions.yml # Centralized test list
│   ├── playbooks/
│   │   ├── libvirt/             # Libvirt-specific playbooks
│   │   │   └── build-golden-image.yml
│   │   ├── aws/                 # AWS playbooks (future)
│   │   ├── azure/               # Azure playbooks (future)
│   │   └── run-tests.yml        # Provider-agnostic test runner
│   ├── tasks/
│   │   └── run-test-with-infrastructure.yml
│   └── roles/                   # Reusable roles
│       ├── download_image/
│       ├── golden_image/
│       ├── bootstrap_sparrowdo/
│       ├── provision_vm/
│       ├── run_test/
│       └── cleanup_vm/
├── scripts/                     # Shell scripts (libvirt only)
│   ├── download-image.sh
│   ├── build-golden.sh
│   ├── run-test.sh
│   └── cleanup_vm.sh
└── docs/
    ├── ANSIBLE-GUIDE.md
    └── BOOTSTRAP-APPROACH.md

Ansible Roles

Role	Purpose
download_image	Download and cache QCOW2 images
golden_image	Build golden image with virt-customize
bootstrap_sparrowdo	Bootstrap Sparrowdo on golden image
provision_vm	Provision VM as linked clone
run_test	Execute test workflow
cleanup_vm	Clean up VMs and disks

Shell Scripts

Script	Purpose
download-image.sh	Download and cache QCOW2 images
build-golden.sh	Build golden image
bootstrap_golden.sh	Bootstrap Sparrowdo
run-test.sh	Run single test
provision_vm.sh	Create VM
cleanup_vm.sh	Cleanup single VM
cleanup-all.sh	Cleanup multiple VMs

Test Definitions

Ansible

Edit ansible/vars/test-definitions.yml to add tests:

tests:
  - name: "Sparky_Knot"
    repo_url: "https://git.resf.org/testing/Sparky_Knot.git"
    # Optional: branch, timeout

  - name: "ssh-test"
    repo_url: "https://github.com/your-org/ssh-test.git"
    branch: "develop"
    timeout: 600

Test Repository Format

Your test repository needs sparrowfile or main.raku:

#!/usr/bin/env raku
use Sparrowdo;

task-run 'check-sshd', %(
    plugin => 'systemd-service',
    args => ['sshd', 'running']
);

Configuration

Ansible

Provider Groups:

• inventory/hosts.yml - Provider groups (libvirt, aws, azure)
• inventory/group_vars/all.yml - Settings for all providers
• inventory/group_vars/libvirt.yml - Libvirt-specific (VM resources, packages)
• inventory/group_vars/aws.yml - AWS-specific (future)
• inventory/group_vars/azure.yml - Azure-specific (future)

Test Definitions:

• vars/test-definitions.yml - Centralized test repository list

Example override:

ansible-playbook playbooks/run-tests.yml -e "vm_memory=4096"

Shell Scripts

Pass parameters directly:

./scripts/provision_vm.sh <vm_name> <golden_image> [timeout]

Documentation

• Ansible Guide - Complete Ansible documentation
• Bootstrap Approach - How golden image works

Key Features

Ansible Implementation

• Provider-aware - Supports libvirt, AWS, Azure (cloud providers in progress)
• Interactive prompts - No need to remember image URLs
• Test definitions - Centralized test list in vars/test-definitions.yml
• Result tracking - Shows passed/failed tests with summary report
• Automatic cleanup - Infrastructure cleaned up after each test

Troubleshooting

# List VMs
virsh -c qemu:///system list --all

# Get VM IP
virsh -c qemu:///system domifaddr <vm-name>

# SSH to VM
ssh -i ~/.ssh/id_rsa rocky@<vm-ip>

# Ansible verbose mode
ansible-playbook playbooks/run-tests.yml -vvv

# Run specific test
ansible-playbook playbooks/run-tests.yml -e "test_filter=Sparky_Knot"

License

[Your License Here]

Authors

Rocky Linux Testing Team