Organize documentation: move all markdown files to docs/ directory
- Created docs/ directory for better organization - Moved 35 markdown files from root to docs/ - Includes all status reports, guides, and testing documentation Co-Authored-By: Warp <agent@warp.dev>
This commit is contained in:
Warp Agent
249
docs/VTL-TESTING-GUIDE.md
Normal file
249
docs/VTL-TESTING-GUIDE.md
Normal file
@@ -0,0 +1,249 @@
|
||||
# VTL Testing Guide
|
||||
|
||||
This guide provides step-by-step instructions for testing the Virtual Tape Library (VTL) endpoints.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. **API Server Running**: The Calypso API should be running on `http://localhost:8080`
|
||||
2. **Authentication Token**: You need a valid JWT token (get it via login)
|
||||
3. **Backing Store Directory**: Ensure `/var/lib/calypso/vtl` exists or is writable
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Get Authentication Token
|
||||
|
||||
```bash
|
||||
# Login and save token
|
||||
TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username":"admin","password":"admin123"}' | jq -r '.token')
|
||||
|
||||
# Save to file for scripts
|
||||
echo "$TOKEN" > /tmp/calypso-test-token
|
||||
```
|
||||
|
||||
### 2. Run Automated Tests
|
||||
|
||||
```bash
|
||||
./scripts/test-vtl.sh
|
||||
```
|
||||
|
||||
## Manual Testing
|
||||
|
||||
### Test 1: List Libraries (Initially Empty)
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/api/v1/tape/vtl/libraries \
|
||||
-H "Authorization: Bearer $TOKEN" | jq .
|
||||
```
|
||||
|
||||
**Expected**: Empty array `{"libraries": []}`
|
||||
|
||||
### Test 2: Create a VTL Library
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/v1/tape/vtl/libraries \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "vtl-test-01",
|
||||
"description": "Test Virtual Tape Library",
|
||||
"backing_store_path": "/var/lib/calypso/vtl",
|
||||
"slot_count": 10,
|
||||
"drive_count": 2
|
||||
}' | jq .
|
||||
```
|
||||
|
||||
**Expected Response**:
|
||||
```json
|
||||
{
|
||||
"id": "uuid-here",
|
||||
"name": "vtl-test-01",
|
||||
"description": "Test Virtual Tape Library",
|
||||
"mhvtl_library_id": 1,
|
||||
"backing_store_path": "/var/lib/calypso/vtl/vtl-test-01",
|
||||
"slot_count": 10,
|
||||
"drive_count": 2,
|
||||
"is_active": true,
|
||||
"created_at": "...",
|
||||
"updated_at": "...",
|
||||
"created_by": "..."
|
||||
}
|
||||
```
|
||||
|
||||
**What Happens**:
|
||||
- Creates directory: `/var/lib/calypso/vtl/vtl-test-01/tapes/`
|
||||
- Creates 2 virtual drives in database
|
||||
- Creates 10 virtual tapes (V00001 through V00010) with empty image files
|
||||
- Each tape is 800 GB (LTO-8 default)
|
||||
|
||||
### Test 3: Get Library Details
|
||||
|
||||
```bash
|
||||
LIBRARY_ID="your-library-id-here"
|
||||
|
||||
curl http://localhost:8080/api/v1/tape/vtl/libraries/$LIBRARY_ID \
|
||||
-H "Authorization: Bearer $TOKEN" | jq .
|
||||
```
|
||||
|
||||
**Expected**: Full library details with drives and tapes arrays
|
||||
|
||||
### Test 4: List Drives
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/api/v1/tape/vtl/libraries/$LIBRARY_ID/drives \
|
||||
-H "Authorization: Bearer $TOKEN" | jq .
|
||||
```
|
||||
|
||||
**Expected**: Array of 2 drives with status "idle"
|
||||
|
||||
### Test 5: List Tapes
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/api/v1/tape/vtl/libraries/$LIBRARY_ID/tapes \
|
||||
-H "Authorization: Bearer $TOKEN" | jq .
|
||||
```
|
||||
|
||||
**Expected**: Array of 10 tapes with barcodes V00001-V00010
|
||||
|
||||
### Test 6: Load a Tape
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/v1/tape/vtl/libraries/$LIBRARY_ID/load \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"slot_number": 1,
|
||||
"drive_number": 1
|
||||
}' | jq .
|
||||
```
|
||||
|
||||
**Expected Response**:
|
||||
```json
|
||||
{
|
||||
"task_id": "uuid-here"
|
||||
}
|
||||
```
|
||||
|
||||
**Check Task Status**:
|
||||
```bash
|
||||
TASK_ID="task-id-from-above"
|
||||
|
||||
curl http://localhost:8080/api/v1/tasks/$TASK_ID \
|
||||
-H "Authorization: Bearer $TOKEN" | jq .
|
||||
```
|
||||
|
||||
**After Load**:
|
||||
- Tape status changes from "idle" to "in_drive"
|
||||
- Drive status changes from "idle" to "ready"
|
||||
- Drive's `current_tape_id` is set
|
||||
|
||||
### Test 7: Get Library (After Load)
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/api/v1/tape/vtl/libraries/$LIBRARY_ID \
|
||||
-H "Authorization: Bearer $TOKEN" | jq .
|
||||
```
|
||||
|
||||
**Verify**:
|
||||
- Drive 1 shows status "ready" and has `current_tape_id`
|
||||
- Tape in slot 1 shows status "in_drive"
|
||||
|
||||
### Test 8: Unload a Tape
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/v1/tape/vtl/libraries/$LIBRARY_ID/unload \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"drive_number": 1,
|
||||
"slot_number": 1
|
||||
}' | jq .
|
||||
```
|
||||
|
||||
**After Unload**:
|
||||
- Tape status changes back to "idle"
|
||||
- Drive status changes back to "idle"
|
||||
- Drive's `current_tape_id` is cleared
|
||||
|
||||
### Test 9: Create Additional Tape
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/v1/tape/vtl/libraries/$LIBRARY_ID/tapes \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"barcode": "CUSTOM001",
|
||||
"slot_number": 11,
|
||||
"tape_type": "LTO-8",
|
||||
"size_gb": 15000
|
||||
}' | jq .
|
||||
```
|
||||
|
||||
**Expected**: New tape created with custom barcode and 15 TB size
|
||||
|
||||
### Test 10: Delete Library (Optional)
|
||||
|
||||
**Note**: Library must be inactive first
|
||||
|
||||
```bash
|
||||
# First, deactivate library (would need update endpoint or direct DB)
|
||||
# Then delete:
|
||||
curl -X DELETE http://localhost:8080/api/v1/tape/vtl/libraries/$LIBRARY_ID \
|
||||
-H "Authorization: Bearer $TOKEN" | jq .
|
||||
```
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
- [ ] Library creation succeeds
|
||||
- [ ] Directory structure created correctly
|
||||
- [ ] Initial tapes created (10 tapes with barcodes V00001-V00010)
|
||||
- [ ] Drives created (2 drives, status "idle")
|
||||
- [ ] Load operation works (tape moves to drive, status updates)
|
||||
- [ ] Unload operation works (tape returns to slot, status updates)
|
||||
- [ ] Custom tape creation works
|
||||
- [ ] Task status tracking works for async operations
|
||||
- [ ] Database state persists correctly
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Error: "failed to create backing store directory"
|
||||
- **Solution**: Ensure `/var/lib/calypso/vtl` exists and is writable:
|
||||
```bash
|
||||
sudo mkdir -p /var/lib/calypso/vtl
|
||||
sudo chown $USER:$USER /var/lib/calypso/vtl
|
||||
```
|
||||
|
||||
### Error: "library not found"
|
||||
- **Solution**: Check that you're using the correct library ID from the create response
|
||||
|
||||
### Error: "tape not found in slot"
|
||||
- **Solution**: Verify slot number exists and has a tape. List tapes first to see available slots.
|
||||
|
||||
### Error: "no tape in drive"
|
||||
- **Solution**: Load a tape to the drive before attempting to unload.
|
||||
|
||||
## Expected File Structure
|
||||
|
||||
After creating a library, you should see:
|
||||
|
||||
```
|
||||
/var/lib/calypso/vtl/vtl-test-01/
|
||||
└── tapes/
|
||||
├── V00001.img
|
||||
├── V00002.img
|
||||
├── V00003.img
|
||||
└── ... (10 files total)
|
||||
```
|
||||
|
||||
Each `.img` file is an empty tape image file (0 bytes initially).
|
||||
|
||||
## Next Steps
|
||||
|
||||
After successful testing:
|
||||
1. Verify database records in `virtual_tape_libraries`, `virtual_tape_drives`, `virtual_tapes`
|
||||
2. Test with multiple libraries
|
||||
3. Test concurrent load/unload operations
|
||||
4. Verify task status tracking
|
||||
5. Check audit logs for all operations
|
||||
|
||||
Reference in New Issue
Block a user