> 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/learn-the-platform/vi/module-8-nha-phat-trien-and-devops/04-terraform-packer.md).

# Terraform & Packer

Hạ tầng dưới dạng mã mang tính khai báo cho VergeOS bằng nhà cung cấp Terraform, OpenTofu và plugin Packer để tự động tạo golden image.

Infrastructure-as-Code (IaC) mang lại cùng khả năng kiểm soát phiên bản, đánh giá chéo và tính lặp lại mà các nhóm phần mềm dựa vào cho việc cung cấp hạ tầng. Phần **nhà cung cấp VergeOS Terraform** cho phép bạn khai báo VM, mạng và người dùng trong các tệp cấu hình HCL, trong khi **plugin Packer** tự động hóa việc tạo image vàng. Kết hợp lại, chúng tạo thành một pipeline khai báo: Packer xây dựng image, Terraform triển khai hạ tầng.

## Nhà cung cấp Terraform

Nhà cung cấp VergeOS Terraform được phát hành trên Terraform Registry và hoàn toàn tương thích với **OpenTofu** (bản fork mã nguồn mở của Terraform). Nó cho phép bạn quản lý tài nguyên VergeOS thông qua các `terraform plan` / `terraform apply` quy trình làm việc.

### Cấu hình nhà cung cấp

```hcl
terraform {
  required_providers {
    vergeio = {
      source  = "verge-io/vergeio"
      version = "~> 2.7"
    }
  }
}

provider "vergeio" {
  host     = "https://vergeos.example.com"
  username = "admin"
  password = var.vergeos_password
  insecure = true  # Đặt thành true cho các chứng chỉ SSL tự ký
}
```

| Tham số      | Bắt buộc | Mô tả                                                        |
| ------------ | -------- | ------------------------------------------------------------ |
| **host**     | Có       | URL hoặc địa chỉ IP của hệ thống VergeOS hoặc tenant         |
| **username** | Có       | Tên người dùng VergeOS với quyền phù hợp                     |
| **password** | Có       | Mật khẩu cho người dùng đã chỉ định (đánh dấu là `nhạy cảm`) |
| **insecure** | Không    | Đặt `true` để chấp nhận các chứng chỉ SSL tự ký              |

{% hint style="success" %}
**Tương thích với OpenTofu**

Cấu hình nhà cung cấp giống hệt cho OpenTofu. Chỉ cần thay `terraform` các lệnh bằng `tofu` — không cần thay đổi mã.
{% endhint %}

### Tài nguyên

Nhà cung cấp hiện hỗ trợ năm loại tài nguyên được quản lý để tạo và cập nhật các đối tượng VergeOS:

| Tài nguyên               | Mục đích                        | Thuộc tính chính                                                                                                                                                                             |
| ------------------------ | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`vergeio_vm`**         | Tạo và quản lý máy ảo           | `cpu_cores`, `ram`, `os_family`, `machine_type`, `ha_group`, `cluster`, `guest_agent`, `uefi`, `secure_boot`, `snapshot_profile`, `powerstate`, inline `vergeio_drive` và `vergeio_nic` khối |
| **`vergeio_network`**    | Cấu hình mạng ảo                | `network` (CIDR), `dhcp_enabled`, `dhcp_start`, `dhcp_stop`, `vnet_default_gateway`, `powerstate`                                                                                            |
| **`vergeio_user`**       | Cung cấp người dùng             | Quản lý tài khoản người dùng trong VergeOS                                                                                                                                                   |
| **`vergeio_member`**     | Quản lý tư cách thành viên nhóm | Gán người dùng vào nhóm cho RBAC                                                                                                                                                             |
| **`vergeio_tag_member`** | Gán thẻ cho các đối tượng       | Đính kèm thẻ vào VM, mạng và các đối tượng VergeOS khác (VergeOS v26+)                                                                                                                       |

### Nguồn dữ liệu

Mười nguồn dữ liệu chỉ đọc cho phép bạn truy vấn các đối tượng VergeOS hiện có để dùng trong cấu hình của bạn:

| Nguồn dữ liệu                 | Trả về                                                  |
| ----------------------------- | ------------------------------------------------------- |
| **`vergeio_version`**         | Thông tin phiên bản VergeOS hiện tại                    |
| **`vergeio_clusters`**        | Các cụm tính toán/lưu trữ khả dụng                      |
| **`vergeio_nodes`**           | Các node trong môi trường                               |
| **`vergeio_networks`**        | Các mạng ảo hiện có                                     |
| **`vergeio_vms`**             | Máy ảo (có thể lọc theo tên, trạng thái snapshot)       |
| **`vergeio_groups`**          | Nhóm người dùng cho RBAC                                |
| **`vergeio_mediasources`**    | ISO và tệp media đã tải lên                             |
| **`vergeio_cloudinitfiles`**  | Các tệp cấu hình cloud-init khả dụng                    |
| **`vergeio_resource_groups`** | Các nhóm tài nguyên phần cứng (PCI, USB, các pool vGPU) |
| **`vergeio_tags`**            | Các thẻ được cấu hình trong VergeOS                     |

### Ví dụ HCL

#### VM với Drive và NIC

Ví dụ này tạo một máy chủ web Linux với một ổ đĩa virtio-scsi 10 GB và một NIC gắn vào mạng nội bộ:

```hcl
resource "vergeio_vm" "web_server" {
  name                 = "my-web-server"
  description          = "Web Server"
  enabled              = true
  os_family            = "linux"
  cpu_cores            = 2
  machine_type         = "q35"
  ram                  = 2048
  powerstate           = false
  guest_agent          = true
  cloudinit_datasource = "nocloud"
  ha_group             = "web"

  # Lưu trữ
  vergeio_drive {
    name           = "Web Server OS Disk"
    description    = "Ổ đĩa Hệ điều hành"
    disksize       = 10
    interface      = "virtio-scsi"
    preferred_tier = 3
    orderid        = 0
  }

  # Mạng
  vergeio_nic {
    name        = "Web Server Network"
    description = "NIC cho Web Server"
    interface   = "virtio"
    enabled     = true
    vnet        = vergeio_network.web_network.id
  }
}
```

#### Mạng nội bộ với DHCP

```hcl
resource "vergeio_network" "web_network" {
  name         = "web-internal-network"
  network      = "192.168.10.0/24"
  dhcp_enabled = true
  dhcp_start   = "192.168.10.100"
  dhcp_stop    = "192.168.10.200"
}
```

#### Truy vấn các VM hiện có

Dùng nguồn dữ liệu để tham chiếu đến hạ tầng hiện có mà không quản lý nó:

```hcl
data "vergeio_vms" "production" {
  filter_name = "prod-db"
  is_snapshot  = false
}

output "production_vms" {
  value = data.vergeio_vms.production.vms
}
```

#### Tích hợp Cloud-Init

Tài nguyên `vergeio_vm` hỗ trợ cloud-init cho tự động hóa khi khởi động lần đầu. Lược đồ của nhà cung cấp hiển thị một `cloudinit_datasource` thuộc tính trên VM và một `vergeio_cloudinitfiles` nguồn dữ liệu để tham chiếu các tệp cloud-init đã tồn tại trong VergeOS:

```hcl
resource "vergeio_vm" "app_server" {
  name                 = "app-server-01"
  os_family            = "linux"
  cpu_cores            = 4
  machine_type         = "q35"
  ram                  = 8192
  guest_agent          = true
  cloudinit_datasource = "nocloud"

  vergeio_drive {
    name           = "OS Disk"
    disksize       = 20
    interface      = "virtio-scsi"
    preferred_tier = 2
  }

  vergeio_nic {
    interface = "virtio"
    vnet      = vergeio_network.web_network.id
  }
}
```

Để biết cú pháp chính xác dùng để đính kèm tệp cloud-init trực tiếp trong tài nguyên VM (thay vì tham chiếu các tệp đã tải lên trước qua nguồn dữ liệu), hãy xem [kho lưu trữ nhà cung cấp](https://github.com/verge-io/terraform-provider-vergeio) — dạng trường cụ thể có thể thay đổi giữa các bản phát hành.

### Mức độ trưởng thành & Lộ trình

{% hint style="warning" %}
**Kiểm tra phạm vi hỗ trợ tài nguyên hiện tại**

Nhà cung cấp VergeOS Terraform đang được phát triển tích cực, và chưa phải mọi đối tượng VergeOS đều được hiển thị dưới dạng tài nguyên được quản lý. Ví dụ về các khu vực có thể chưa có phạm vi hỗ trợ đầy đủ tại một thời điểm nhất định gồm cung cấp tenant, quản lý snapshot profile và cấu hình mạng external/WAN.

Luôn kiểm tra [kho lưu trữ GitHub](https://github.com/verge-io/terraform-provider-vergeio) và danh sách trên Terraform Registry để xem phạm vi tài nguyên hiện tại và ghi chú phát hành trước khi thiết kế cấu hình dựa trên chúng.
{% endhint %}

## Plugin Packer

Tài nguyên **Plugin Packer cho VergeOS** (`github.com/verge-io/packer-plugin-vergeio`) tự động hóa việc tạo image VM trực tiếp trên nền tảng VergeOS. Trong khi Terraform quản lý hạ tầng đang chạy, Packer tập trung vào việc xây dựng **các image vàng** làm nền tảng cho các triển khai.

### Tại sao dùng Packer?

```mermaid
flowchart LR
    A["Base ISO"] --> B["Packer Build"]
    B --> C["Cài đặt gói<br/>Gia cố OS<br/>Cấu hình dịch vụ"]
    C --> D["Image vàng"]
    D --> E["VM Recipe"]
    D --> F["Triển khai Terraform"]
    D --> G["Cung cấp thủ công"]

    style B fill:#4a9eff,color:#fff
    style D fill:#2ecc71,color:#fff
```

Image vàng đảm bảo mọi VM được triển khai đều bắt đầu từ một nền tảng cơ sở đã biết, đã kiểm thử và đã được gia cố. Thay vì cung cấp một OS trống và chạy các script cấu hình trên mỗi lần triển khai, Packer đóng gói sẵn image một lần:

* **Tính nhất quán** — Mọi VM được tạo từ image đều giống hệt nhau
* **Tốc độ** — Không có độ trễ cung cấp khi khởi động lần đầu; VM sẵn sàng ngay
* **Tuân thủ** — Các đường cơ sở bảo mật và bản vá được tích hợp sẵn trong lúc build
* **Tích hợp pipeline** — Kích hoạt xây dựng lại image từ CI/CD vào ngày vá OS

### Cấu hình plugin

Plugin Packer được khai báo trong khối `required_plugins` cùng với một `source` và `build` cho image đích. Tên trường chính xác cho khối `source "vergeio"` (endpoint, thông tin xác thực, kích thước VM, tùy chọn đĩa, v.v.) nên lấy từ kho lưu trữ của plugin, vì chúng có thể thay đổi giữa các bản phát hành:

* [`verge-io/packer-plugin-vergeio` trên GitHub](https://github.com/verge-io/packer-plugin-vergeio)

Một khai báo `required_plugins` điển hình sẽ như sau:

```hcl
packer {
  required_plugins {
    vergeio = {
      source  = "github.com/verge-io/vergeio"
      version = ">= 0.1.1"
    }
  }
}
```

### Khả năng

Ở mức cao, plugin điều khiển toàn bộ vòng đời build của Packer thông qua API VergeOS — tạo một VM tạm thời, chạy các provisioner và thu lại image kết quả. Để biết lược đồ cấu hình chính xác, các kiểu guest được hỗ trợ và hành vi tắt dọn dẹp, hãy tham khảo trực tiếp kho lưu trữ của plugin:

* [`verge-io/packer-plugin-vergeio` trên GitHub](https://github.com/verge-io/packer-plugin-vergeio)

### Pipeline Packer → Recipe

Image Packer tích hợp một cách tự nhiên với **Recipe** của VergeOS. Một quy trình điển hình:

1. **Packer** xây dựng và gia cố image vàng theo lịch (ví dụ: chu kỳ vá hàng tháng)
2. Image được đăng ký dưới dạng một **VM Recipe** trong VergeOS Marketplace
3. Người dùng triển khai các VM chuẩn hóa từ recipe — thông qua giao diện hoặc qua Terraform
4. Cập nhật diễn ra tự động: xây dựng lại image Packer, cập nhật recipe, và mọi triển khai mới đều nhận phiên bản mới nhất

## Mẫu quy trình IaC

### Quy trình chỉ dùng Terraform

Dành cho các nhóm muốn hạ tầng khai báo mà không có pipeline image:

```mermaid
flowchart LR
    A["Cấu hình HCL"] --> B["terraform plan"]
    B --> C["terraform apply"]
    C --> D["API VergeOS"]
    D --> E["VM + Mạng<br/>Được tạo"]

    style B fill:#7b42f5,color:#fff
    style C fill:#4a9eff,color:#fff
```

### Pipeline đầy đủ (Packer + Terraform)

Dành cho môi trường sản xuất có quản lý image vàng:

```mermaid
flowchart LR
    A["Base ISO"] --> B["Packer Build"]
    B --> C["Image vàng"]
    C --> D["Triển khai Terraform"]
    D --> E["VM sản xuất"]
    F["Kích hoạt CI/CD"] -.-> B

    style B fill:#2ecc71,color:#fff
    style D fill:#4a9eff,color:#fff
```

### Kết hợp với các công cụ khác

Terraform xử lý việc cung cấp; các công cụ quản lý cấu hình xử lý phần còn lại:

| Giai đoạn     | Công cụ                       | Mục đích                           |
| ------------- | ----------------------------- | ---------------------------------- |
| **Tạo image** | Packer                        | Xây dựng image vàng đã được gia cố |
| **Cung cấp**  | Terraform                     | Triển khai VM, mạng, người dùng    |
| **Cấu hình**  | Ansible / cloud-init          | Cấu hình phần mềm sau triển khai   |
| **Giám sát**  | Prometheus / cảnh báo VergeOS | Theo dõi hạ tầng đã triển khai     |

{% hint style="info" %}
**Cầu nối VMware**

Trên VMware, nhà cung cấp vSphere của Terraform quản lý ESXi/vCenter/vSAN như các mối quan tâm riêng biệt và Packer dùng `vsphere-iso` builder thông qua vCenter. Nhà cung cấp VergeOS `vergeio` duy nhất xử lý VM, mạng, ổ đĩa và người dùng thông qua một endpoint API, và plugin Packer nhắm tới cùng API đó.
{% endhint %}

{% hint style="info" %}
**Cầu nối Nutanix**

Nhà cung cấp Nutanix Terraform (`nutanix/nutanix`) và plugin Packer đều nhắm tới API v3 của Prism Central. Nhà cung cấp VergeOS giao tiếp với một endpoint duy nhất (URL hệ thống hoặc tenant VergeOS) mà không có instance quản lý riêng, và hiển thị cấu hình cloud-init trực tiếp trên `vergeio_vm` tài nguyên thông qua `cloudinit_datasource` thuộc tính và `vergeio_cloudinitfiles` nguồn dữ liệu.
{% endhint %}

## Các thực tiễn tốt nhất

### Quản lý trạng thái

* **Sử dụng backend trạng thái từ xa** (S3, Consul, Terraform Cloud) để cộng tác nhóm
* **Đừng bao giờ commit** `terraform.tfstate` vào kiểm soát phiên bản — nó có thể chứa thông tin xác thực
* **Khóa các tệp trạng thái** để ngăn sửa đổi đồng thời trong môi trường nhiều người dùng

### Bảo mật

* **Sử dụng biến** cho các giá trị nhạy cảm (`var.vergeos_password`) — không bao giờ hardcode thông tin xác thực
* **Đánh dấu output nhạy cảm** bằng `sensitive = true` để tránh lộ ra ngoài ý muốn trong log
* **Hạn chế quyền của nhà cung cấp** — tạo một người dùng API VergeOS riêng với quyền truy cập tối thiểu cần thiết

### Tổ chức module

* **Tách các môi trường** thành workspace hoặc thư mục (`dev/`, `staging/`, `prod/`)
* **Tạo các module có thể tái sử dụng** cho các mẫu phổ biến (ví dụ: một module "web-server" với VM + mạng + quy tắc tường lửa)
* **Cố định phiên bản provider** để tránh các thay đổi gây lỗi bất ngờ khi nâng cấp

## Đọc thêm

* [Terraform Provider — GitHub](https://github.com/verge-io/terraform-provider-vergeio)
* [Terraform Registry — VergeIO Provider](https://registry.terraform.io/providers/verge-io/vergeio/latest)
* [Packer Plugin — GitHub](https://github.com/verge-io/packer-plugin-vergeio)
* [OpenTofu Registry — VergeIO Provider](https://search.opentofu.org/provider/verge-io/vergeio/latest)
* [Tài liệu VergeOS — Terraform Provider](https://docs.verge.io/product-guide/tools-integrations/terraform-provider/)


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.verge.io/learn-the-platform/vi/module-8-nha-phat-trien-and-devops/04-terraform-packer.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.