> 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/zh/mo-kuai-8-kai-fa-zhe-yu-devops/04-terraform-packer.md).

# Terraform 与 Packer

使用 Terraform 提供程序、OpenTofu 和 Packer 插件为 VergeOS 实现声明式基础设施即代码，自动创建黄金镜像。

基础设施即代码（IaC）将软件团队依赖的版本控制、同行评审和可重复性带到基础设施交付中。该 **VergeOS Terraform 提供程序** 使您可以在 HCL 配置文件中声明虚拟机、网络和用户，而 **Packer 插件** 自动化创建黄金镜像。两者结合形成一条声明式流水线：Packer 构建镜像，Terraform 部署基础设施。

## Terraform 提供程序

VergeOS Terraform 提供程序已发布在 Terraform Registry 上，并且完全兼容 **OpenTofu** （Terraform 的开源分支）。它使您能够通过标准的 `terraform plan` / `terraform apply` 工作流。

### 提供程序配置

```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  # 对自签名 SSL 证书设置为 true
}
```

| 参数           | 必需 | 描述                         |
| ------------ | -- | -------------------------- |
| **host**     | 是  | VergeOS 系统或租户的 URL 或 IP 地址 |
| **username** | 是  | 具有适当权限的 VergeOS 用户名        |
| **password** | 是  | 指定用户的密码（标记为 `敏感`)          |
| **insecure** | 否  | 设置 `true` 以接受自签名 SSL 证书    |

{% hint style="success" %}
**与 OpenTofu 兼容**

OpenTofu 的提供程序配置完全相同。只需将 `terraform` 命令替换为 `tofu` — 无需更改代码。
{% endhint %}

### 资源

当前提供程序支持五种用于创建和更新 VergeOS 对象的托管资源类型：

| 资源                       | 用途       | 关键属性                                                                                                                                                                                |
| ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`vergeio_vm`**         | 创建和管理虚拟机 | `cpu_cores`, `ram`, `os_family`, `machine_type`, `ha_group`, `cluster`, `guest_agent`, `uefi`, `secure_boot`, `snapshot_profile`, `powerstate`，内联 `vergeio_drive` 和 `vergeio_nic` 块 |
| **`vergeio_network`**    | 配置虚拟网络   | `network` （CIDR）， `dhcp_enabled`, `dhcp_start`, `dhcp_stop`, `vnet_default_gateway`, `powerstate`                                                                                   |
| **`vergeio_user`**       | 配置用户     | VergeOS 内的用户账户管理                                                                                                                                                                    |
| **`vergeio_member`**     | 管理组成员关系  | 将用户与组关联以进行 RBAC                                                                                                                                                                     |
| **`vergeio_tag_member`** | 为对象分配标签  | 将标签附加到虚拟机、网络和其他 VergeOS 对象（VergeOS v26+）                                                                                                                                            |

### 数据源

十个只读数据源可让您查询现有的 VergeOS 对象，以便在配置中使用：

| 数据源                           | 返回                    |
| ----------------------------- | --------------------- |
| **`vergeio_version`**         | 当前 VergeOS 版本信息       |
| **`vergeio_clusters`**        | 可用的计算/存储集群            |
| **`vergeio_nodes`**           | 环境中的节点                |
| **`vergeio_networks`**        | 现有虚拟网络                |
| **`vergeio_vms`**             | 虚拟机（可按名称、快照状态筛选）      |
| **`vergeio_groups`**          | 用于 RBAC 的用户组          |
| **`vergeio_mediasources`**    | 已上传的 ISO 和媒体文件        |
| **`vergeio_cloudinitfiles`**  | 可用的 cloud-init 配置文件   |
| **`vergeio_resource_groups`** | 硬件资源组（PCI、USB、vGPU 池） |
| **`vergeio_tags`**            | 在 VergeOS 中配置的标签      |

### HCL 示例

#### 带磁盘和网卡的虚拟机

此示例创建一台 Linux Web 服务器，配备 10 GB virtio-scsi 磁盘和一个连接到内部网络的网卡：

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

  # 存储
  vergeio_drive {
    name           = "Web Server OS Disk"
    description    = "Operating System Disk"
    disksize       = 10
    interface      = "virtio-scsi"
    preferred_tier = 3
    orderid        = 0
  }

  # 网络
  vergeio_nic {
    name        = "Web Server Network"
    description = "NIC for Web Server"
    interface   = "virtio"
    enabled     = true
    vnet        = vergeio_network.web_network.id
  }
}
```

#### 启用 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"
}
```

#### 查询现有虚拟机

使用数据源引用现有基础设施，而无需对其进行管理：

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

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

#### Cloud-Init 集成

该 `vergeio_vm` 资源支持用于首次启动自动化的 cloud-init。提供程序架构暴露了一个 `cloudinit_datasource` 虚拟机上的属性，以及一个 `vergeio_cloudinitfiles` 用于引用 VergeOS 中已存在的 cloud-init 文件的数据源：

```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
  }
}
```

要了解在 VM 资源上以内联方式附加 cloud-init 文件所使用的确切语法（与通过数据源引用预上传文件相比），请查阅 [提供程序仓库](https://github.com/verge-io/terraform-provider-vergeio) — 字段级格式可能会在版本之间演变。

### 成熟度与路线图

{% hint style="warning" %}
**查看当前资源覆盖范围**

VergeOS Terraform 提供程序仍在积极开发中，并非每个 VergeOS 对象都已作为托管资源公开。某些时间点可能尚未获得完整提供程序覆盖的领域示例包括租户配置、快照配置文件管理以及外部/WAN 网络配置。

始终查看 [GitHub 仓库](https://github.com/verge-io/terraform-provider-vergeio) 以及 Terraform Registry 列表中的当前资源覆盖范围和发布说明，然后再围绕它们设计配置。
{% endhint %}

## Packer 插件

该 **VergeOS 的 Packer 插件** (`github.com/verge-io/packer-plugin-vergeio`）可直接在 VergeOS 平台上自动创建 VM 镜像。Terraform 负责管理运行中的基础设施，而 Packer 专注于构建 **黄金镜像** 这些镜像作为部署的基础。

### 为什么选择 Packer？

```mermaid
flowchart LR
    A["基础 ISO"] --> B["Packer 构建"]
    B --> C["安装软件包<br/>加固操作系统<br/>配置服务"]
    C --> D["黄金镜像"]
    D --> E["VM 配方"]
    D --> F["Terraform 部署"]
    D --> G["手动配置"]

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

黄金镜像确保每台已部署的虚拟机都从已知、经过测试且已加固的基线开始。Packer 不会在每次部署时先配置裸操作系统并运行配置脚本，而是一次性预先烘焙镜像：

* **一致性** — 从该镜像创建的每台虚拟机都完全相同
* **速度** — 无首次启动配置延迟；虚拟机可立即就绪
* **合规性** — 安全基线和补丁在构建时已内置
* **流水线集成** — 在操作系统补丁日通过 CI/CD 触发镜像重建

### 插件配置

Packer 插件在一个中声明 `required_plugins` 块中，与一个 `source` 和 `build` 用于目标镜像。以下 `source "vergeio"` 块（端点、凭据、VM 规格、磁盘选项等）的确切字段名称应以插件仓库为准，因为它们可能会在版本之间演变：

* [`verge-io/packer-plugin-vergeio` 在 GitHub 上](https://github.com/verge-io/packer-plugin-vergeio)

一个典型的 `required_plugins` 声明如下：

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

### 功能

从高层来看，该插件通过 VergeOS API 驱动完整的 Packer 构建生命周期——创建临时虚拟机、运行 provisioner，并捕获生成的镜像。有关准确的配置模式、支持的来宾类型以及关机/清理行为，请直接参考插件仓库：

* [`verge-io/packer-plugin-vergeio` 在 GitHub 上](https://github.com/verge-io/packer-plugin-vergeio)

### Packer → 配方流水线

Packer 镜像可自然集成到 VergeOS **配方** 系统中。典型工作流程如下：

1. **Packer** 按计划构建并加固黄金镜像（例如每月补丁周期）
2. 该镜像被注册为 **VM 配方** 在 VergeOS Marketplace 中
3. 用户从配方部署标准化虚拟机——可以通过 UI 或 Terraform
4. 更新会自动流转：重建 Packer 镜像、更新配方，所有新的部署都会获得最新版本

## IaC 工作流模式

### 仅使用 Terraform 的工作流

适用于希望获得声明式基础设施但不需要镜像流水线的团队：

```mermaid
flowchart LR
    A["HCL 配置"] --> B["terraform plan"]
    B --> C["terraform apply"]
    C --> D["VergeOS API"]
    D --> E["虚拟机 + 网络<br/>已创建"]

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

### 完整流水线（Packer + Terraform）

适用于带有黄金镜像管理的生产环境：

```mermaid
flowchart LR
    A["基础 ISO"] --> B["Packer 构建"]
    B --> C["黄金镜像"]
    C --> D["Terraform 部署"]
    D --> E["生产虚拟机"]
    F["CI/CD 触发器"] -.-> B

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

### 与其他工具结合使用

Terraform 负责配置；其余部分由配置管理工具处理：

| 阶段       | 工具                      | 用途          |
| -------- | ----------------------- | ----------- |
| **镜像创建** | Packer                  | 构建加固的黄金镜像   |
| **配置**   | Terraform               | 部署虚拟机、网络、用户 |
| **配置**   | Ansible / cloud-init    | 部署后的软件配置    |
| **监控**   | Prometheus / VergeOS 告警 | 观察已部署的基础设施  |

{% hint style="info" %}
**VMware 桥接**

在 VMware 上，Terraform 的 vSphere 提供程序将 ESXi/vCenter/vSAN 作为独立关注点进行管理，而 Packer 使用 `vsphere-iso` 构建器通过 vCenter。单一的 VergeOS `vergeio` 提供程序通过一个 API 端点处理虚拟机、网络、磁盘和用户，而 Packer 插件也针对同一 API。
{% endhint %}

{% hint style="info" %}
**Nutanix 桥接**

Nutanix Terraform 提供程序（`nutanix/nutanix`）和 Packer 插件都指向 Prism Central 的 v3 API。VergeOS 提供程序只与单一端点（VergeOS 系统或租户 URL）通信，没有单独的管理实例，并直接在 `vergeio_vm` 资源上通过 `cloudinit_datasource` 属性以及 `vergeio_cloudinitfiles` 数据源公开 cloud-init 配置。
{% endhint %}

## 最佳实践

### 状态管理

* **使用远程状态后端** （S3、Consul、Terraform Cloud）以便团队协作
* **切勿提交** `terraform.tfstate` 到版本控制中——它可能包含凭据
* **锁定状态文件** 以防止在多用户环境中发生并发修改

### 安全

* **使用变量** 用于敏感值（`var.vergeos_password`）——切勿硬编码凭据
* **将敏感输出标记为** 使用 `sensitive = true` 以防止在日志中意外暴露
* **限制提供程序权限** — 创建一个具有最低所需访问权限的专用 VergeOS API 用户

### 模块组织

* **将环境分离** 到工作区或目录中（`dev/`, `staging/`, `prod/`)
* **创建可复用模块** 用于常见模式（例如，一个带有虚拟机 + 网络 + 防火墙规则的“web-server”模块）
* **锁定提供程序版本** 以避免升级期间出现意外的破坏性变更

## 延伸阅读

* [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)
* [VergeOS 文档 — Terraform Provider](https://docs.verge.io/automate-protect-and-extend/zh/ji-cheng-yu-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/zh/mo-kuai-8-kai-fa-zhe-yu-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.
