For the complete documentation index, see llms.txt. This page is also available as Markdown.

Terraform 与 Packer

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

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

Terraform 提供程序

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

提供程序配置

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 证书

资源

当前提供程序支持五种用于创建和更新 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 磁盘和一个连接到内部网络的网卡:

启用 DHCP 的内部网络

查询现有虚拟机

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

Cloud-Init 集成

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

要了解在 VM 资源上以内联方式附加 cloud-init 文件所使用的确切语法(与通过数据源引用预上传文件相比),请查阅 提供程序仓库 — 字段级格式可能会在版本之间演变。

成熟度与路线图

Packer 插件

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

为什么选择 Packer?

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

  • 一致性 — 从该镜像创建的每台虚拟机都完全相同

  • 速度 — 无首次启动配置延迟;虚拟机可立即就绪

  • 合规性 — 安全基线和补丁在构建时已内置

  • 流水线集成 — 在操作系统补丁日通过 CI/CD 触发镜像重建

插件配置

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

一个典型的 required_plugins 声明如下:

功能

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

Packer → 配方流水线

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

  1. Packer 按计划构建并加固黄金镜像(例如每月补丁周期)

  2. 该镜像被注册为 VM 配方 在 VergeOS Marketplace 中

  3. 用户从配方部署标准化虚拟机——可以通过 UI 或 Terraform

  4. 更新会自动流转:重建 Packer 镜像、更新配方,所有新的部署都会获得最新版本

IaC 工作流模式

仅使用 Terraform 的工作流

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

完整流水线(Packer + Terraform)

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

与其他工具结合使用

Terraform 负责配置;其余部分由配置管理工具处理:

阶段
工具
用途

镜像创建

Packer

构建加固的黄金镜像

配置

Terraform

部署虚拟机、网络、用户

配置

Ansible / cloud-init

部署后的软件配置

监控

Prometheus / VergeOS 告警

观察已部署的基础设施

VMware 桥接

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

Nutanix 桥接

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

最佳实践

状态管理

  • 使用远程状态后端 (S3、Consul、Terraform Cloud)以便团队协作

  • 切勿提交 terraform.tfstate 到版本控制中——它可能包含凭据

  • 锁定状态文件 以防止在多用户环境中发生并发修改

安全

  • 使用变量 用于敏感值(var.vergeos_password)——切勿硬编码凭据

  • 将敏感输出标记为 使用 sensitive = true 以防止在日志中意外暴露

  • 限制提供程序权限 — 创建一个具有最低所需访问权限的专用 VergeOS API 用户

模块组织

  • 将环境分离 到工作区或目录中(dev/, staging/, prod/)

  • 创建可复用模块 用于常见模式(例如,一个带有虚拟机 + 网络 + 防火墙规则的“web-server”模块)

  • 锁定提供程序版本 以避免升级期间出现意外的破坏性变更

延伸阅读

最后更新于

这有帮助吗?