> 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-yu-devops/04-terraform-packer.md).

# Terraform 与 Packer

基础设施即代码（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 = "~> 0.1.0"
    }
  }
}

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`, `集群`, `guest_agent`, `uefi`, `secure_boot`, `snapshot_profile`, `powerstate`，内联 `vergeio_drive` 以及 `vergeio_nic` 块 |
| **`vergeio_network`** | 配置虚拟网络   | `network_address` （CIDR）， `dhcp_enabled`, `dhcp_start`, `dhcp_end`, `dns_server_list`, `gateway`, `powerstate`                                                                  |
| **`vergeio_user`**    | 提供用户     | VergeOS 内的用户账户管理                                                                                                                                                                |
| **`vergeio_member`**  | 管理组成员关系  | 将用户关联到组以实现 RBAC                                                                                                                                                                 |

### 数据源

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

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

### 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 服务器 OS 磁盘"
    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_address = "192.168.10.0/24"
  dns_server_list = ["8.8.8.8", "8.8.4.4"]
  dhcp_enabled    = true
  dhcp_start      = "192.168.10.100"
  dhcp_end        = "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 用于首次启动自动化。提供程序 schema 暴露一个 `cloudinit_datasource` VM 上的属性，以及一个 `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
  }
}
```

有关在 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，并捕获生成的镜像。有关确切的配置 schema、支持的来宾类型以及关机/清理行为，请直接参阅插件仓库：

* [`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 通过 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` 数据源。
{% endhint %}

## 最佳实践

### 状态管理

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

### 安全

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

### 模块组织

* **将环境分离** 到工作区或目录中（`dev/`, `staging/`, `prod/`)
* **创建可复用模块** 用于常见模式（例如包含 VM + 网络 + 防火墙规则的“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 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/learn-the-platform/zh/mo-kuai-8-kai-fa-yu-devops/04-terraform-packer.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.