> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/knowledge-base/vi/automation-api/vm-creation-api.md).

# API tạo VM

{% hint style="info" %}
**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
  {% endhint %}

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`](/knowledge-base/vi/automation-api/vm-power-management.md)
* Cấu hình cài đặt → [`Cấu hình VM`](/knowledge-base/vi/automation-api/vm-configuration.md)
* Thao tác nâng cao → [`Các thao tác nâng cao của VM`](/knowledge-base/vi/automation-api/vm-advanced-operations.md)

## 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

```bash
-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`](/knowledge-base/vi/automation-api/vm-power-management.md))

## 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

```bash
# 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**:

```json
{
  "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**:

```json
{
  "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

{% hint style="success" %}
**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
  {% endhint %}

## 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

```json
{
  "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

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

**Ví dụ phản hồi**:

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

### Gắn CDROM/ISO

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

**Ví dụ phản hồi**:

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

### Nhập từ nguồn media

```json
{
  "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

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

**Ví dụ phản hồi**:

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

{% hint style="success" %}
**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
  {% endhint %}

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

```bash
# 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ụ**:

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

**Ví dụ phản hồi**:

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

{% hint style="info" %}
**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.
{% endhint %}

## 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:

```bash
# 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": {}
  }'
```

{% hint style="info" %}
**Các thao tác liên quan**

* **Quản lý nguồn điện**: xem [`Quản lý nguồn VM`](/knowledge-base/vi/automation-api/vm-power-management.md) để khởi động/dừng VM
* **Cấu hình**: xem [`Cấu hình VM`](/knowledge-base/vi/automation-api/vm-configuration.md) để thay đổi CPU/RAM
* **Các thao tác nâng cao**: xem [`Các thao tác nâng cao của VM`](/knowledge-base/vi/automation-api/vm-advanced-operations.md) để sao chép và snapshot
  {% endhint %}

{% hint style="info" %}
**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
  {% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.verge.io/knowledge-base/vi/automation-api/vm-creation-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.