40c1ecc6fe
All pages now use native Vuetify components directly. Flash messages are handled by the ToastStack component via Pinia store. Notifications use NotificationPanel. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
133 lines
3.8 KiB
Markdown
133 lines
3.8 KiB
Markdown
# VirtFusion V6 API Integration
|
|
|
|
## Overview
|
|
EZSCALE uses VirtFusion V6 for VPS provisioning and management. This document outlines the correct API endpoints and parameters.
|
|
|
|
## API Reference
|
|
**OpenAPI Spec**: `virtfusion-api-spec.yaml` (8,309 lines)
|
|
**Base URL**: Configured in `.env` as `VIRTFUSION_API_URL`
|
|
**Authentication**: Bearer token (configured as `VIRTFUSION_API_TOKEN`)
|
|
|
|
## Correct API Endpoints (V6)
|
|
|
|
### Connection Test
|
|
```http
|
|
GET /connect
|
|
Authorization: Bearer {token}
|
|
```
|
|
**Response**: Returns VirtFusion version and connection status
|
|
|
|
### Create Server
|
|
```http
|
|
POST /servers
|
|
Content-Type: application/json
|
|
Authorization: Bearer {token}
|
|
|
|
{
|
|
"packageId": 1, // Required: VirtFusion package ID
|
|
"userId": 1, // Required: VirtFusion user ID (not email!)
|
|
"hypervisorId": 1 // Required: Hypervisor group ID
|
|
}
|
|
```
|
|
**Response**: Returns server object with ID, UUID, state, IP addresses, etc.
|
|
|
|
### Get Server Details
|
|
```http
|
|
GET /servers/{serverId}
|
|
Authorization: Bearer {token}
|
|
```
|
|
**Response**: Full server details including state, suspended status, traffic, etc.
|
|
|
|
### Suspend Server
|
|
```http
|
|
POST /servers/{serverId}/suspend
|
|
Authorization: Bearer {token}
|
|
```
|
|
**Response**: 204 No Content on success
|
|
|
|
### Unsuspend Server
|
|
```http
|
|
POST /servers/{serverId}/unsuspend
|
|
Authorization: Bearer {token}
|
|
```
|
|
**Response**: 204 No Content on success
|
|
|
|
### Delete Server
|
|
```http
|
|
DELETE /servers/{serverId}?delay=0
|
|
Authorization: Bearer {token}
|
|
```
|
|
**Query Parameters**:
|
|
- `delay`: Minutes to wait before deletion (0-43800), optional
|
|
|
|
**Response**: 204 No Content on success
|
|
|
|
## Plan Configuration
|
|
|
|
VPS plans in the database need these feature keys:
|
|
|
|
```json
|
|
{
|
|
"virtfusion_package_id": 1, // Required: VirtFusion package ID
|
|
"virtfusion_user_id": 1, // Required: VirtFusion user ID for server owner
|
|
"virtfusion_hypervisor_id": 1 // Required: Hypervisor group ID
|
|
}
|
|
```
|
|
|
|
## Key Differences from Other Versions
|
|
|
|
1. **No `/api/v1` prefix** - V6 endpoints start directly with resource names
|
|
2. **camelCase parameters** - Use `packageId` not `package_id`
|
|
3. **userId not email** - Must provide VirtFusion user ID, not email address
|
|
4. **Suspend returns 204** - No response body, check for 204 status code
|
|
|
|
## Implementation Files
|
|
|
|
- **Service**: `app/Services/Provisioning/VirtFusionService.php`
|
|
- **Settings Controller**: `app/Http/Controllers/Admin/SettingsController.php` (testVirtFusion method)
|
|
- **Config**: `config/services.php` (virtfusion section)
|
|
|
|
## Testing
|
|
|
|
Test connection via Admin Settings page:
|
|
1. Navigate to Admin → Settings → API Credentials
|
|
2. Enter VirtFusion API URL and Token
|
|
3. Click "Test Connection"
|
|
4. Should return: "VirtFusion connection successful. Version: X.X.X"
|
|
|
|
## API Restrictions
|
|
|
|
According to deployment notes, the VirtFusion API token is restricted to:
|
|
- ✅ Create server
|
|
- ✅ Create user
|
|
- ✅ Authenticate user
|
|
|
|
Ensure the token has appropriate permissions for these operations.
|
|
|
|
## Troubleshooting
|
|
|
|
### 404 Errors
|
|
- ❌ Using `/api/v1/servers` (old format)
|
|
- ✅ Use `/servers` (V6 format)
|
|
|
|
### 400 Bad Request
|
|
- Check parameter names are camelCase (`packageId` not `package_id`)
|
|
- Ensure `userId` is an integer, not an email
|
|
- Verify `packageId` and `hypervisorId` exist in VirtFusion
|
|
|
|
### 401 Unauthorized
|
|
- Verify `VIRTFUSION_API_TOKEN` is correct
|
|
- Check token has required permissions
|
|
- Ensure `Authorization: Bearer` header is included
|
|
|
|
### Server Creation Fails
|
|
- Verify plan features include `virtfusion_package_id`, `virtfusion_user_id`, and `virtfusion_hypervisor_id`
|
|
- Check VirtFusion has available resources (RAM, storage, IP addresses)
|
|
- Review `provisioning_logs` table for detailed error messages
|
|
|
|
## Related Documentation
|
|
|
|
- VirtFusion Official Docs: https://docs.virtfusion.com/api/
|
|
- OpenAPI Spec: `/virtfusion-api-spec.yaml`
|
|
- Project Integration: `CLAUDE.md` → Provisioning Services section
|