> 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` 工作流管理 VergeOS 资源。

### 提供程序配置

```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 示例

#### 带驱动器和 NIC 的虚拟机

此示例创建了一个 Linux Web 服务器，配有一个 10 GB virtio-scsi 驱动器和一个连接到内部网络的 NIC：

```hcl
resource "vergeio_vm" "web_server" {
  name                 = "my-web-server"
  description          = "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"

  # 存储
  vergeio_drive {
    name           = "Web 服务器操作系统磁盘"
    description    = "操作系统磁盘"
    disksize       = 10
    interface      = "virtio-scsi"
    preferred_tier = 3
    orderid        = 0
  }

  # 网络
  vergeio_nic {
    name        = "Web 服务器网络"
    description = "用于 Web 服务器的 NIC"
    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           = "操作系统磁盘"
    disksize       = 20
    interface      = "virtio-scsi"
    preferred_tier = 2
  }

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

有关在虚拟机资源上内联附加 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 平台上自动创建虚拟机镜像。Terraform 管理运行中的基础设施，而 Packer 专注于构建 **黄金镜像** ，它们是部署的基础。

### 为什么选择 Packer？

```mermaid
flowchart LR
    A["基础 ISO"] --> B["Packer 构建"]
    B --> C["安装软件包<br/>加固操作系统<br/>配置服务"]
    C --> D["黄金镜像"]
    D --> E["虚拟机配方"]
    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"` 块（端点、凭据、虚拟机规格、磁盘选项等）应从插件代码库获取，因为它们可能会随版本演进：

* [`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 构建生命周期——创建临时虚拟机、运行配置程序并捕获生成的镜像。有关确切的配置架构、支持的客户机类型以及关机/清理行为，请直接参阅插件代码库：

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

### Packer → 配方流水线

Packer 镜像可与 VergeOS 的 **配方** 系统自然集成。典型工作流：

1. **Packer** 按计划构建并加固黄金镜像（例如每月补丁周期）
2. 该镜像被注册为 **虚拟机配方** 在 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 通过 vCenter 使用 `vsphere-iso` 构建器。单一的 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 用户

### 模块组织

* **分离环境** 到工作区或目录中（`开发/`, `预发布/`, `生产/`)
* **创建可复用模块** 用于常见模式（例如，一个包含虚拟机 + 网络 + 防火墙规则的“web-server”模块）
* **固定提供程序版本** 以避免升级过程中出现意外的破坏性变更

## 延伸阅读

* [Terraform 提供程序 — GitHub](https://github.com/verge-io/terraform-provider-vergeio)
* [Terraform Registry — VergeIO 提供程序](https://registry.terraform.io/providers/verge-io/vergeio/latest)
* [Packer 插件 — GitHub](https://github.com/verge-io/packer-plugin-vergeio)
* [OpenTofu Registry — VergeIO 提供程序](https://search.opentofu.org/provider/verge-io/vergeio/latest)
* [VergeOS 文档 — Terraform 提供程序](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/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.