From ab61878fbc128ed1485cdf7b416d0efa8b7944b6 Mon Sep 17 00:00:00 2001 From: Claus Lohmar Date: Tue, 21 Jul 2026 16:50:49 +0000 Subject: [PATCH] chore: restore open-api.yaml --- open-api.yaml | 245 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 245 insertions(+) create mode 100644 open-api.yaml diff --git a/open-api.yaml b/open-api.yaml new file mode 100644 index 0000000..8c2bf6c --- /dev/null +++ b/open-api.yaml @@ -0,0 +1,245 @@ +openapi: 3.0.3 +info: + title: Proxmox Image Conversion Engine + description: | + Backend API that runs on the Proxmox host (`srv2`) to convert VMware images + (VMDK, VHD, etc.) to Proxmox‑compatible QCOW2, optionally shrink the disk, + and provision a VM with automatic boot‑type detection. + version: 1.1.0 + contact: + name: Support + url: https://github.com/your-org/converter + +servers: + - url: http://10.2.0.2:9000/api/v1 + description: Internal Proxmox host (srv2) + +paths: + /jobs: + post: + summary: Submit a new VM conversion and creation job + operationId: createJob + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/JobSubmissionRequest' + responses: + '202': + description: Job accepted and queued for processing + content: + application/json: + schema: + $ref: '#/components/schemas/JobStatusResponse' + '400': + description: Invalid request or source file not found + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + /jobs/{job_id}: + get: + summary: Get the current status of a conversion job + operationId: getJobStatus + parameters: + - name: job_id + in: path + required: true + schema: + type: string + example: "job_10007_1784637888" + responses: + '200': + description: Job status details + content: + application/json: + schema: + $ref: '#/components/schemas/JobStatusResponse' + '404': + description: Job not found + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + /jobs/{job_id}/cleanup: + post: + summary: Delete staging files or preserve them for reuse + operationId: cleanupJob + parameters: + - name: job_id + in: path + required: true + schema: + type: string + example: "job_10007_1784637888" + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CleanupRequest' + responses: + '200': + description: Cleanup action performed + content: + application/json: + schema: + type: object + properties: + job_id: + type: string + action_taken: + type: string + enum: [purged, retained] + message: + type: string + + /health: + get: + summary: Health check endpoint + operationId: healthCheck + responses: + '200': + description: Service is healthy + content: + application/json: + schema: + type: object + properties: + status: + type: string + example: ok + +components: + schemas: + DiskSpec: + type: object + required: + - disk_type + properties: + disk_type: + type: string + enum: [image_file, empty_disk] + description: | + `image_file` – convert an existing file from `source_filename`. + `empty_disk` – create a blank disk of the given `size_gb`. + source_filename: + type: string + nullable: true + description: Path relative to `/mnt/converter/in` (required if `disk_type=image_file`) + example: "64bit/Debian 12.11.0 (64bit).vmdk" + size_gb: + type: integer + nullable: true + description: Size in GiB (required if `disk_type=empty_disk`) + example: 50 + format: + type: string + enum: [qcow2, raw, vmdk] + default: qcow2 + description: Source image format (for `image_file`) + + JobSubmissionRequest: + type: object + required: + - vmid + - vm_name + - boot_disk + properties: + vmid: + type: integer + description: Proxmox VM ID (must be unique on host) + example: 10007 + vm_name: + type: string + description: Display name for the VM + example: "debian-default-shrink" + boot_type: + type: string + enum: [uefi, legacy] + default: uefi + description: Boot firmware type (ignored if `auto_detect_boot=true`) + auto_detect_boot: + type: boolean + default: true + description: | + If `true`, automatically detects whether the disk is EFI‑bootable and + overrides `boot_type`. Falls back to `legacy` if detection fails. + cpu_cores: + type: integer + default: 4 + minimum: 1 + example: 2 + ram_mb: + type: integer + default: 8192 + minimum: 512 + example: 4096 + target_storage: + type: string + default: "local-lvm" + description: Proxmox storage pool for the VM disks + example: "local-lvm" + boot_disk: + $ref: '#/components/schemas/DiskSpec' + additional_disks: + type: array + items: + $ref: '#/components/schemas/DiskSpec' + description: Additional data disks (converted or empty) + target_disk_size_gb: + type: integer + nullable: true + description: | + If provided, the boot disk (and only the boot disk) is resized to this + size (GiB). If omitted and the boot disk is larger than 30 GiB, it is + automatically shrunk to 30 GiB. Only shrinks when disk_type=image_file. + example: 40 + + JobStatusResponse: + type: object + properties: + job_id: + type: string + example: "job_10007_1784637888" + vmid: + type: integer + example: 10007 + status: + type: string + enum: [queued, processing_conversion, importing_storage, completed, failed] + description: Current job phase + progress_percentage: + type: integer + minimum: 0 + maximum: 100 + example: 75 + message: + type: string + description: Human‑readable status message + example: "Creating VM and importing disks..." + error_details: + type: string + nullable: true + description: If status is `failed`, contains the error reason + + CleanupRequest: + type: object + required: + - delete_staging_files + properties: + delete_staging_files: + type: boolean + description: | + `true` – delete extracted source files and converted disk images. + `false` – keep files so another VM can be created from the same source. + + ErrorResponse: + type: object + properties: + detail: + type: string + example: "Source file not found: 64bit/Debian 12.11.0 (64bit).vmdk"