resf-testing-repo/ansible/README.md

# Ansible Implementation

This directory contains the Ansible-based implementation of the Rocky Linux Testing Framework with provider-aware infrastructure support.

## Quick Start

```bash
cd ansible

# 1. Build golden image (libvirt only)
ansible-playbook playbooks/libvirt/build-golden-image.yml

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

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

## Documentation

See [ANSIBLE-GUIDE.md](../docs/ANSIBLE-GUIDE.md) for complete documentation.

## Structure

```
ansible/
├── ansible.cfg              # Ansible configuration
├── inventory/
│   ├── hosts.yml           # Provider groups (libvirt, aws, azure)
│   └── group_vars/
│       ├── all.yml         # Provider-agnostic variables
│       ├── libvirt.yml     # Libvirt-specific settings
│       ├── aws.yml         # AWS-specific settings (placeholder)
│       └── azure.yml       # Azure-specific settings (placeholder)
├── vars/
│   └── test-definitions.yml # Test repository list
├── tasks/
│   └── run-test-with-infrastructure.yml # Provider-aware orchestration
├── playbooks/
│   ├── libvirt/            # Libvirt-specific playbooks
│   │   └── build-golden-image.yml
│   ├── aws/                # AWS-specific playbooks (future)
│   ├── azure/              # Azure-specific playbooks (future)
│   └── run-tests.yml       # Provider-agnostic test runner
└── roles/
    ├── download_image/     # Download QCOW2 images
    ├── golden_image/       # Build golden image
    ├── bootstrap_sparrowdo/# Bootstrap Sparrowdo
    ├── provision_vm/       # Provision VMs (libvirt)
    ├── run_test/          # Execute Sparrowdo tests
    └── cleanup_vm/        # Cleanup VMs (libvirt)
```

## Roles

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

## Playbooks

### Provider-Agnostic
| Playbook | Purpose |
|----------|---------|
| `run-tests.yml` | Run tests from test-definitions.yml (works on any provider) |

### Libvirt-Specific
| Playbook | Purpose |
|----------|---------|
| `libvirt/build-golden-image.yml` | Build golden image with interactive prompts |

### Future
- `aws/` - AWS-specific setup playbooks
- `azure/` - Azure-specific setup playbooks

## Configuration

### Provider Groups

The inventory is organized by provider type:
- **libvirt** - Local VM testing (requires golden image)
- **aws** - AWS EC2 testing (uses AMIs, ready for implementation)
- **azure** - Azure VM testing (uses VM images, ready for implementation)

### Test Definitions

Edit `vars/test-definitions.yml` to add/modify tests:
```yaml
tests:
  - name: "Sparky_Knot"
    repo_url: "https://git.resf.org/testing/Sparky_Knot.git"
    # Optional: branch, timeout
```

### Provider-Specific Settings

- **all.yml** - Settings for all providers (SSH, Sparrowdo, etc.)
- **libvirt.yml** - VM resources, image paths, packages
- **aws.yml** - AMI IDs, instance types (when implemented)
- **azure.yml** - Image references, VM sizes (when implemented)

## Examples

### Build Golden Image (Libvirt Only)

```bash
# Interactive prompt for Rocky image URL
ansible-playbook playbooks/libvirt/build-golden-image.yml
```

### Run All Tests

```bash
ansible-playbook playbooks/run-tests.yml
```

### Run Specific Test

```bash
ansible-playbook playbooks/run-tests.yml -e "test_filter=Sparky_Knot"
```

### Run Tests on Specific Provider

```bash
ansible-playbook playbooks/run-tests.yml --limit libvirt
# Future: --limit aws or --limit azure
```

### Override VM Resources

```bash
ansible-playbook playbooks/run-tests.yml -e "vm_memory=4096" -e "vm_vcpus=4"
```

## Troubleshooting

### Verbose Output

```bash
ansible-playbook playbooks/run-tests.yml -vvv
```

### Check Syntax

```bash
ansible-playbook playbooks/libvirt/build-golden-image.yml --syntax-check
```

### List Tasks

```bash
ansible-playbook playbooks/run-tests.yml --list-tasks
```

## Key Features

- **Provider-aware** - Supports multiple infrastructure providers (libvirt, AWS, Azure)
- **Test definitions** - Centralized test repository list in `vars/test-definitions.yml`
- **Interactive prompts** - No need to remember image URLs or flags
- **Result tracking** - Shows passed/failed tests with summary report
- **Automatic cleanup** - Infrastructure cleaned up after each test
- **Idempotent** - Safe to re-run
- **Integration with Ascender** - Works with Ansible automation platform

### Script Mapping

| Shell Script | Ansible Role |
|--------------|--------------|
| `download-image.sh` | `download_image` |
| `setup_base.sh` + `build-golden.sh` | `golden_image` |
| `bootstrap_golden.sh` | `bootstrap_sparrowdo` |
| `provision_vm.sh` | `provision_vm` |
| `run-test.sh` | `run_test` |
| `cleanup_vm.sh` | `cleanup_vm` |

## Prerequisites

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

## License

[Your License Here]