API tạo VM

Hướng dẫn đầy đủ về tạo máy ảo trong VergeOS, bao gồm tạo cơ bản, cấu hình theo recipe, ổ đĩa, thiết bị và giao diện mạng

Các điểm chính

• Tạo VM với các tham số cấu hình thiết yếu bằng REST API
• Hỗ trợ tạo VM dựa trên recipe với các cấu hình phức tạp
• Thêm ổ đĩa, thiết bị và giao diện mạng sau khi tạo VM
• Hiểu sự khác biệt giữa VM key và Machine key cho các thao tác khác nhau

Hướng dẫn này bao gồm việc tạo máy ảo trong VergeOS, từ tạo VM cơ bản đến thêm ổ đĩa, thiết bị và giao diện mạng. API VergeOS cung cấp các endpoint toàn diện cho việc tạo VM và cấu hình phần cứng.

Giai đoạn: Tạo VM (1/4) Đầu vào: thông tin xác thực API, thông tin cụm, đặc tả VM Đầu ra: VM key (42) + Machine key (54) Tiếp theo: Sử dụng các khóa để quản lý nguồn điện Các bước tiếp theo phổ biến:

• Bật VM → Quản lý nguồn VM
• Cấu hình cài đặt → Cấu hình VM
• Thao tác nâng cao → Các thao tác nâng cao của VM

Tài liệu này hỗ trợ

• "Cách tạo VM qua API"
• "Thêm ổ đĩa trong quá trình thiết lập VM"
• "Gắn thiết bị GPU/PCI vào VM"
• "Tạo VM với cloud-init"
• "Hiểu VM key so với machine key"
• "Thiết lập giao diện mạng cho VM mới"
• "Cấp phát VM dựa trên recipe"
• "Tự động hóa tạo VM hàng loạt"
• "Triển khai VM theo mô hình hạ tầng dưới dạng mã"

Tham khảo nhanh

Các endpoint chính

• Tạo VM: POST /api/v4/vms
• Thêm ổ đĩa: POST /api/v4/machine_drives
• Thêm thiết bị: POST /api/v4/machine_devices
• Thêm NIC: POST /api/v4/machine_nics

Tham số chính

• name: định danh VM (bắt buộc)
• cluster: ID cụm đích
• machine: ID máy từ quá trình tạo VM (dùng để thêm phần cứng)
• resource_group: UUID cho passthrough thiết bị

Xác thực

-H "Authorization: Bearer YOUR_API_KEY"
-H "Content-Type: application/json"

Các bước tiếp theo

Sau khi tạo VM → Quản lý nguồn điện (Quản lý nguồn VM)

Tham khảo nhanh API

Thao tác	Phương thức	Endpoint	Loại khóa	Mục đích
Tạo VM	POST	/api/v4/vms	Trả về cả hai	Tạo ban đầu
Thêm ổ đĩa	POST	/api/v4/machine_drives	Machine key	Phần cứng
Thêm thiết bị	POST	/api/v4/machine_devices	Machine key	Passthrough GPU/PCI
Thêm NIC	POST	/api/v4/machine_nics	Machine key	Giao diện mạng
Bật nguồn	POST	/api/v4/vm_actions	VM key	Điều khiển
Kiểm tra trạng thái	GET	/api/v4/machine_status/{id}	Machine key	Giám sát

Chỉ mục khắc phục sự cố

• 409 Xung đột: tên VM đã tồn tại, đang chạy, quyền bị từ chối
• 400 Yêu cầu không hợp lệ: tham số không hợp lệ, thiếu trường bắt buộc, JSON không hợp lệ
• 507 Không đủ dung lượng lưu trữ: tầng đã đầy, giảm kích thước, chọn tầng khác
• 403 Bị cấm: quyền của khóa API, truy cập cụm bị từ chối
• 404 Không tìm thấy: ID cụm không hợp lệ, thiếu nguồn media, resource group không hợp lệ
• 422 Không thể xử lý: giao diện ổ đĩa không hợp lệ, kiểu media không được hỗ trợ

Điều kiện tiên quyết

• Thông tin xác thực API VergeOS hợp lệ với quyền quản lý VM
• Hiểu các khái niệm VergeOS: cụm, vnet, nguồn media và resource group
• Kiến thức cơ bản về nguyên tắc REST API và định dạng JSON

Xác thực

Tất cả các thao tác tạo VM đều yêu cầu xác thực bằng một trong các cách sau:

• Khóa API: Bao gồm trong Authorization header dưới dạng Bearer YOUR_API_KEY
• Xác thực cơ bản: Tên người dùng và mật khẩu cho các phiên tương tác
• Token phiên: Dành cho tích hợp dựa trên web

# Sử dụng khóa API
curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     https://your-vergeos.example.com/api/v4/vms

Tạo VM cơ bản

POST /api/v4/vms

Mô tả: Tạo một máy ảo mới với cấu hình được chỉ định.

Tham số yêu cầu:

Tên	Loại	Bắt buộc	Mô tả
name	chuỗi	Có	Tên VM duy nhất
description	chuỗi	Không	Mô tả VM
cluster	chuỗi	Không	ID cụm đích (chuỗi số)
ram	số nguyên	Không	RAM tính bằng MB (mặc định: 1024)
cpu_cores	số nguyên	Không	Số lõi CPU (mặc định: 1)
guest_agent	chuỗi	Không	Bật guest agent ("true"/"false")
console_pass_hash	chuỗi	Không	Mã băm mật khẩu console (chuỗi rỗng nếu không dùng)
video	chuỗi	Không	Kiểu bộ điều hợp video (virtio, std, cirrus, v.v.)
rtc_base	chuỗi	Không	Thiết lập cơ sở RTC (utc, localtime)
uefi	chuỗi	Không	Bật khởi động UEFI ("true"/"false")

Ví dụ nội dung yêu cầu:

{
  "name": "web-server-01",
  "description": "Máy chủ web sản xuất",
  "cluster": "1",
  "ram": 8192,
  "cpu_cores": 4,
  "guest_agent": "true",
  "console_pass_hash": "",
  "video": "virtio",
  "rtc_base": "utc",
  "uefi": "true"
}

Ví dụ phản hồi:

{
  "location": "/v4/vms/42",
  "dbpath": "vms/42",
  "$row": 42,
  "$key": "42",
  "response": {
    "machine": "54"
  }
}

Các trường phản hồi:

Trường	Loại	Mô tả
location	chuỗi	Endpoint API cho VM đã tạo
dbpath	chuỗi	Đường dẫn cơ sở dữ liệu cho bản ghi VM
$row	số nguyên	Số hàng trong cơ sở dữ liệu
$key	chuỗi	ID VM (được dùng cho các cuộc gọi API tiếp theo)
response.machine	chuỗi	ID máy (được dùng cho ổ đĩa, NIC, thiết bị)

Phản hồi lỗi:

• 400 Yêu cầu không hợp lệ: tham số cấu hình không hợp lệ
• 409 Xung đột: tên VM đã tồn tại
• 403 Bị cấm: không đủ quyền

VM Key so với Machine Key

• VM key (ví dụ, "42"): Dùng cho cài đặt VM như CPU, RAM, console
• Machine key (ví dụ, "54"): Dùng cho phần cứng như ổ đĩa, NIC, thiết bị
• Bạn sẽ nhận được cả hai khóa trong phản hồi tạo VM

Tạo VM dựa trên recipe

VergeOS hỗ trợ tạo VM phức tạp bằng các recipe bao gồm ổ đĩa, giao diện mạng và thiết bị.

VM hoàn chỉnh với cấu hình recipe

{
  "name": "enterprise-vm",
  "description": "Máy chủ ứng dụng doanh nghiệp",
  "cluster": "1",
  "cpu_cores": 8,
  "ram": 16384,
  "guest_agent": "true",
  "video": "virtio",
  "rtc_base": "utc",
  "uefi": "true",
  "secure_boot": "true",
  "console_pass_hash": "",
  "cloudinit_datasource": "nocloud",
  "cloudinit_files": [
    {
      "name": "user-data",
      "contents": "#cloud-config\nusers:\n  - name: admin\n    sudo: ALL=(ALL) NOPASSWD:ALL\n    ssh_authorized_keys:\n      - ssh-rsa AAAAB3NzaC1yc2E..."
    },
    {
      "name": "meta-data",
      "contents": "instance-id: enterprise-vm-001\nlocal-hostname: enterprise-vm"
    }
  ]
}

Thêm ổ đĩa

Ổ đĩa phải được tạo riêng sau khi tạo VM bằng endpoint machine drives.

POST /api/v4/machine_drives

Tham số yêu cầu:

Tên	Loại	Bắt buộc	Mô tả
machine	chuỗi	Có	ID máy từ quá trình tạo VM
name	chuỗi	Không	Tên ổ đĩa
media	chuỗi	Không	Loại media (disk, cdrom, import, clone, efidisk)
interface	chuỗi	Không	Giao diện ổ đĩa (virtio-scsi, ide, ahci, v.v.)
disksize	số nguyên	Không	Dung lượng ổ đĩa tính bằng byte (cho ổ đĩa mới)
preferred_tier	chuỗi	Không	Tầng lưu trữ (1-5)
media_source	chuỗi	Không	ID media nguồn (cho import/clone/cdrom)
show_pt	chuỗi	Không	Ghi đè tầng ưu tiên ("true"/"false") - ghi đè tầng mặc định của media nguồn

Tạo ổ đĩa khởi động

{
  "machine": "54",
  "name": "Ổ đĩa HĐH",
  "media": "disk",
  "interface": "virtio-scsi",
  "disksize": 2199023255552,
  "preferred_tier": "1"
}

Ví dụ phản hồi:

{
  "location": "/v4/machine_drives/54",
  "dbpath": "machine_drives/54",
  "$row": 54,
  "$key": "54"
}

Gắn CDROM/ISO

{
  "machine": "54",
  "media": "cdrom",
  "interface": "ahci",
  "media_source": "7"
}

Ví dụ phản hồi:

{
  "location": "/v4/machine_drives/55",
  "dbpath": "machine_drives/55",
  "$row": 55,
  "$key": "55"
}

Nhập từ nguồn media

{
  "machine": "54",
  "name": "Ubuntu Server",
  "description": "Ubuntu 22.04 LTS",
  "interface": "virtio-scsi",
  "media": "import",
  "media_source": 123,
  "preferred_tier": "3"
}

Thêm thiết bị (GPU, passthrough PCI, v.v.)

POST /api/v4/machine_devices

Mô tả: gắn các thiết bị phần cứng như GPU, thiết bị PCI, thiết bị USB hoặc TPM vào máy ảo.

Tham số yêu cầu:

Tên	Loại	Bắt buộc	Mô tả
machine	chuỗi	Có	ID máy
resource_group	chuỗi	Có	UUID của resource group cho thiết bị
settings_args	đối tượng	Không	Cài đặt dành riêng cho thiết bị (đối tượng rỗng cho passthrough cơ bản)

GPU passthrough PCI

{
  "machine": "54",
  "resource_group": "1f67f07e-f653-db95-c475-01b8a2ea0ff1",
  "settings_args": {}
}

Ví dụ phản hồi:

{
  "location": "/v4/machine_devices/2",
  "dbpath": "machine_devices/2",
  "$row": 2,
  "$key": "2",
  "response": {
    "uuid": "934e250b-a13c-bd8f-104d-a31995b06eba"
  }
}

Tìm resource group

Tham số resource_group xác định thiết bị phần cứng cụ thể cần gắn. Dùng các endpoint này để tìm các UUID resource group khả dụng:

• GET /api/v4/resource_groups - Thiết bị phần cứng chung (GPU, thiết bị PCI, USB, v.v.)
• GET /api/v4/node_nvidia_vgpu_devices - Cụ thể là các thiết bị NVIDIA vGPU

Tìm các thiết bị khả dụng

# Thiết bị phần cứng chung
curl "https://your-vergeos.example.com/api/v4/resource_groups" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Thiết bị NVIDIA vGPU
curl "https://your-vergeos.example.com/api/v4/node_nvidia_vgpu_devices" \
  -H "Authorization: Bearer YOUR_API_KEY"

Thêm giao diện mạng

POST /api/v4/machine_nics

Tham số yêu cầu:

Tên	Loại	Bắt buộc	Mô tả
machine	chuỗi	Có	ID máy
vnet	chuỗi	Có	ID mạng ảo (khóa của mạng đích)
name	chuỗi	Không	Tên NIC
interface	chuỗi	Không	Loại giao diện NIC (virtio, e1000, v.v.)
đã bật	boolean	Không	Trạng thái bật của NIC

Ví dụ:

{
  "machine": "54",
  "vnet": "3"
}

Ví dụ phản hồi:

{
  "location": "/v4/machine_nics/78",
  "dbpath": "machine_nics/78",
  "$row": 78,
  "$key": "78"
}

Khóa mạng ảo

Tham số vnet tham số sử dụng khóa/ID của mạng. Ví dụ, vnet "3" có thể là mạng ngoài của bạn. Bạn có thể tìm khóa mạng bằng cách liệt kê các mạng khả dụng qua endpoint API networks.

Ví dụ tạo VM hoàn chỉnh

Đây là quy trình làm việc đầy đủ để tạo VM với ổ đĩa, thiết bị và giao diện mạng:

# Bước 1: Tạo VM
curl -X POST "https://your-vergeos.example.com/api/v4/vms" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-server",
    "description": "Máy chủ ứng dụng sản xuất",
    "cluster": "1",
    "ram": 16384,
    "cpu_cores": 8,
    "guest_agent": "true",
    "video": "virtio",
    "uefi": "true"
  }'

# Phản hồi: VM key = 42, Machine key = 54

# Bước 2: Thêm ổ đĩa khởi động
curl -X POST "https://your-vergeos.example.com/api/v4/machine_drives" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "machine": "54",
    "name": "Boot Drive",
    "media": "disk",
    "interface": "virtio-scsi",
    "disksize": 107374182400,
    "preferred_tier": "1"
  }'

# Bước 3: Thêm giao diện mạng
curl -X POST "https://your-vergeos.example.com/api/v4/machine_nics" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "machine": "54",
    "vnet": "3"
  }'

# Bước 4: Thêm GPU (tùy chọn)
curl -X POST "https://your-vergeos.example.com/api/v4/machine_devices" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "machine": "54",
    "resource_group": "1f67f07e-f653-db95-c475-01b8a2ea0ff1",
    "settings_args": {}
  }'

Các thao tác liên quan

• Quản lý nguồn điện: xem Quản lý nguồn VM để khởi động/dừng VM
• Cấu hình: xem Cấu hình VM để thay đổi CPU/RAM
• Các thao tác nâng cao: xem Các thao tác nâng cao của VM để sao chép và snapshot

Cần trợ giúp?

Để được hỗ trợ thêm về tạo VM:

• Kiểm tra cổng tài liệu VergeOS
• Liên hệ bộ phận hỗ trợ VergeOS với các thông báo lỗi cụ thể
• Xem lại nhật ký hệ thống để biết thông tin lỗi chi tiết
• Tham khảo các diễn đàn cộng đồng VergeOS