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

Hạ tầng dưới dạng mã (IaC) mang lại cùng kiểm soát phiên bản, đánh giá ngang hàng và khả năng lặp lại mà các nhóm phần mềm dựa vào để cung cấp hạ tầng. Phần **trì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. Cùng nhau, chúng tạo thành một pipeline khai báo: Packer xây dựng các image, Terraform triển khai hạ tầng.

## Trình cung cấp Terraform

Trì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** (nhánh Terraform mã nguồn mở). 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 trì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 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 hoặc tenant VergeOS         |
| **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 chứng chỉ SSL tự ký                  |

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

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

### Tài nguyên

Trì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`, nội tuyến `vergeio_drive` và `vergeio_nic` các khối |
| **`vergeio_network`**    | Cấu hình mạng ảo                | `mạng` (CIDR), `dhcp_enabled`, `dhcp_start`, `dhcp_stop`, `vnet_default_gateway`, `powerstate`                                                                                                      |
| **`vergeio_user`**       | Cấp phát 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 | Liên kết người dùng với nhóm cho RBAC                                                                                                                                                               |
| **`vergeio_tag_member`** | Gán thẻ cho đối tượng           | Gắn thẻ cho 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ó để sử dụng trong cấu hình của mình:

| 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 cluster 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`**    | Các tệp ISO và 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, 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          = "Máy chủ Web"
  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           = "Đĩa hệ điều hành máy chủ web"
    description    = "Đĩa hệ điều hành"
    disksize       = 10
    interface      = "virtio-scsi"
    preferred_tier = 3
    orderid        = 0
  }

  # Kết nối mạng
  vergeio_nic {
    name        = "Mạng máy chủ web"
    description = "NIC cho máy chủ web"
    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         = "mạng nội bộ web"
  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ó

Sử dụng các nguồn dữ liệu để tham chiếu 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

Phần `vergeio_vm` tài nguyên hỗ trợ cloud-init cho tự động hóa lần khởi động đầu tiên. Lược đồ của trì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           = "Đĩa hệ điều hành"
    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 nội tuyến vào 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ữ 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 độ hoàn thiện & Lộ trình

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

Trình cung cấp VergeOS Terraform đang được phát triển tích cực, và không 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 đủ của trình cung cấp tại một thời điểm nhất định bao gồm cấp phát tenant, quản lý profile snapshot và cấu hình mạng ngoài/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 để biết 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 xoay quanh chúng.
{% endhint %}

## Plugin Packer

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

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

```mermaid
flowchart LR
    A["ISO cơ sở"] --> B["Bản dựng Packer"]
    B --> C["Cài đặt gói<br/>Gia cố HĐH<br/>Cấu hình dịch vụ"]
    C --> D["Image vàng"]
    D --> E["Công thức VM"]
    D --> F["Triển khai Terraform"]
    D --> G["Cấp phát 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, đã được kiểm thử và được gia cố. Thay vì cấp phát một HĐH trống và chạy các script cấu hình trên mỗi lần triển khai, Packer xây sẵn image một lần:

* **Tính nhất quán** — Mọi VM tạo từ image đều giống hệt
* **Tốc độ** — Không có độ trễ cấp phát lần khởi động đầu tiên; VM sẵn sàng ngay lập tức
* **Tuân thủ** — Các chuẩn 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 các ngày vá lỗi HĐH

### Cấu hình plugin

Plugin Packer được khai báo trong một `required_plugins` khối cùng với một `source` và `build` cho image đích. Các tên trường chính xác cho `source "vergeio"` khối (điểm cuối, thông tin xác thực, kích thước VM, tùy chọn đĩa, v.v.) nên được 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 `required_plugins` khai báo điển hình trông như sau:

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

### Khả năng

Ở mức tổng quan, plugin điều khiển toàn bộ vòng đời build của Packer đối với API VergeOS — tạo một VM tạm thời, chạy các trình provisioner, và chụp lại image kết quả. Để biết lược đồ cấu hình chính xác, các kiểu máy khách được hỗ trợ và hành vi tắt/cleanup, 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 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á lỗi hàng tháng)
2. Image được đăng ký dưới dạng một **Công thức VM** trong VergeOS Marketplace
3. Người dùng triển khai các VM chuẩn hóa từ công thức — hoặc qua UI hoặc qua Terraform
4. Các cập nhật tự động diễn ra: xây dựng lại image Packer, cập nhật công thức, và mọi lần triển khai mới sẽ nhận phiên bản mới nhất

## Các 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 với quản lý image vàng:

```mermaid
flowchart LR
    A["ISO cơ sở"] --> B["Bản dựng Packer"]
    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ý cấp phát; 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ố |
| **Cấp phát**  | 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 | Quan sát hạ tầng đã triển khai     |

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

Trên VMware, trì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 sử dụng `vsphere-iso` trình xây dựng thông qua vCenter. Trình cung cấp VergeOS đơn lẻ `vergeio` xử lý VM, mạng, ổ đĩa và người dùng thông qua một điểm cuối API duy nhất, và plugin Packer nhắm tới cùng API đó.
{% endhint %}

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

Trình cung cấp Nutanix Terraform (`nutanix/nutanix`) và plugin Packer đều nhắm tới API v3 của Prism Central. Trình cung cấp VergeOS giao tiếp với một điểm cuối duy nhất (URL hệ thống hoặc tenant VergeOS) mà không cần một phiên bản 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 phương pháp hay 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
* **Không bao giờ commit** `terraform.tfstate` vào hệ thống 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`) — đừng bao giờ mã hóa cứng thông tin xác thực
* **Đánh dấu đầu ra nhạy cảm** bằng `sensitive = true` để ngăn lộ ra ngoài vô tình trong log
* **Hạn chế quyền của trình cung cấp** — tạo một người dùng API VergeOS chuyên dụng với quyền truy cập tối thiểu cần thiết

### Tổ chức mô-đun

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

## Đọc thêm

* [Nhà cung cấp Terraform — GitHub](https://github.com/verge-io/terraform-provider-vergeio)
* [Terraform Registry — Nhà cung cấp VergeIO](https://registry.terraform.io/providers/verge-io/vergeio/latest)
* [Plugin Packer — GitHub](https://github.com/verge-io/packer-plugin-vergeio)
* [OpenTofu Registry — Nhà cung cấp VergeIO](https://search.opentofu.org/provider/verge-io/vergeio/latest)
* [Tài liệu VergeOS — Nhà cung cấp Terraform](https://docs.verge.io/automate-protect-and-extend/vi/tich-hop-va-api/terraform-provider.md)


---

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