> 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/automate-protect-and-extend/zh/ji-cheng-yu-api/rancher-integration.md).

# Rancher 集成

## 概述

VergeOS 可与 [Rancher](https://www.rancher.com/) 通过 Docker Machine 节点驱动和 UI 扩展。结合起来，这些组件使我们能够直接从 Rancher 界面在 VergeOS 基础设施上配置和管理 RKE2/K3s 集群。

| 组件                                          | 用途                                |
| ------------------------------------------- | --------------------------------- |
| [Docker Machine 驱动](#docker-machine-driver) | 将 VergeOS 虚拟机作为 Kubernetes 节点进行配置 |
| [UI 扩展](#ui-extension)                      | 向 Rancher 添加 VergeOS 云凭据和机器配置     |

一旦集群运行起来， [Kubernetes 集成](/automate-protect-and-extend/zh/ji-cheng-yu-api/kubernetes-integration.md) 组件（CSI 驱动和云控制器管理器）提供持久存储和节点生命周期管理——这些功能适用于 VergeOS 上的任何 Kubernetes 集群，而不仅仅是由 Rancher 配置的集群。

```mermaid
graph TD
    subgraph rancher["Rancher 服务器"]
        ui["VergeOS 的 UI 扩展"]
        creds["云凭据"] --> driver["Docker Machine 驱动"]
    end

    driver --> vms["VergeOS 虚拟机"]

    subgraph cluster["RKE2/K3s 集群（VergeOS 虚拟机）"]
        ccm["云控制器管理器"]
        csi["CSI 驱动"]
        ccm_features["节点元数据 · 节点生命周期 · 负载均衡器"]
        csi_features["NAS ReadWriteMany · 块存储 ReadWriteOnce"]
        ccm --- ccm_features
        csi --- csi_features
    end

    vms --> cluster
```

### 先决条件

* 具有 API 访问权限的 VergeOS 环境
* 已安装 Rancher Server（v2.10+）
* 运行 Ubuntu 24.04 且已安装 cloud-init 的模板虚拟机
* VergeOS API 密钥（在用户设置中生成）
* `kubectl` 和 `helm` CLI 工具

***

## Docker Machine 驱动

Docker Machine 驱动是 Rancher 集成的基础。它通过 VergeOS API 管理完整的虚拟机生命周期——克隆模板虚拟机、通过 cloud-init 注入 SSH 密钥，以及在配置集群时创建机器。当集群被移除时，驱动会自动删除它创建的虚拟机。

### 工作原理

1. **克隆** 带有请求的机器名称的模板虚拟机
2. **配置** CPU 核心数、内存和 cloud-init（SSH 密钥 + 主机名 + 可选 user-data）
3. **调整** 如果指定了自定义大小，则调整主磁盘大小
4. **连接** 将虚拟机连接到指定网络
5. **启动** 并等待 IP 地址（优先使用 QEMU guest agent；否则回退到网卡 DHCP）

如果任何步骤失败，驱动会自动清理部分创建的虚拟机。

### 模板虚拟机准备

在配置集群之前，我们需要在 VergeOS 中准备一个具有以下条件的模板虚拟机：

**必需：**

* **Ubuntu 24.04** （Noble Numbat）——目前唯一受支持的模板操作系统
* **cloud-init** 已安装并启用——驱动通过 multipart MIME cloud-init 负载注入 SSH 密钥并设置主机名

**推荐：**

* **QEMU guest agent** ——可实现准确的 IP 发现；如果没有它，驱动会回退到网卡 DHCP 租约 IP

{% hint style="success" %}
**Ubuntu 24.04 细节**

驱动会通过 cloud-init 自动处理 Ubuntu 24.04 的若干细节：

* **Netplan DHCP 配置** ——写入与 `en*` 接口匹配的 netplan 配置，其中 `dhcp4: true`，处理克隆之间 PCI 插槽名称的变化
* **Machine-ID 重新生成** ——重新生成 `/etc/machine-id` ，使每个虚拟机都获得唯一的 DHCP 客户端标识符
* **缓存的 DHCP 租约清理** ——删除从模板继承的过期 DHCP 租约
  {% endhint %}

{% hint style="warning" %}
**内存要求**

用于 Rancher 时，每个节点至少分配 **4 GB 内存** （推荐 8 GB）。带 Calico CNI 的单节点 RKE2 集群在 2 GB 内存下会因 OOM 而失败。
{% endhint %}

模板中 **不会** 需要 Docker——Rancher 会通过系统代理安装自己的容器运行时（containerd）。模板只需要 cloud-init 和 guest agent。

### 网络要求

在 `--vergeos-network` 中指定的 VergeOS 网络必须满足以下要求，Rancher 配置的集群才能正常工作。

{% hint style="warning" %}
**需要 DHCP**

该网络必须启用 DHCP。驱动通过 QEMU guest agent 发现节点 IP，没有 DHCP 的情况下克隆的虚拟机将无法获取地址。
{% endhint %}

{% hint style="info" %}
**Rancher 连接性**

节点必须能够访问 Rancher 服务器，且 Rancher 必须能够访问这些节点。确保它们之间开放以下端口：

有关包括节点到节点要求（因 CNI 而异）的完整端口矩阵，请参见 [Rancher RKE2 端口要求](https://docs.rke2.io/install/requirements#networking) .
{% endhint %}

| 方向           | 端口   | 协议  | 用途                 |
| ------------ | ---- | --- | ------------------ |
| 节点 → Rancher | 443  | TCP | 系统代理注册和通信          |
| Rancher → 节点 | 9345 | TCP | RKE2 节点注册          |
| Rancher → 节点 | 6443 | TCP | Kubernetes API 服务器 |
| 节点 → 互联网     | 443  | TCP | 从镜像仓库拉取容器镜像        |

### 在 Rancher 中安装

节点驱动和 UI 扩展被打包在一个 Helm chart 中。它会安装 Docker Machine 驱动二进制文件，注册 NodeDriver 资源，并部署 UI 扩展。

**通过 Helm CLI：**

```bash
helm repo add verge-io https://verge-io.github.io/helm-charts
helm repo update

helm install vergeos-node-driver verge-io/vergeos-node-driver \
  -n cattle-system \
  --set "vergeosHosts={vergeos.example.com}"
```

该 `vergeosHosts` 值是 Rancher 代理允许访问的 VergeOS 主机名白名单。请将 `vergeos.example.com` 替换为 VergeOS 环境的主机名。

**通过 Rancher UI：**

1. 导航到 **扩展** 并点击 **⋮** 菜单 > **管理仓库**
2. 添加一个新仓库，URL 为 `https://verge-io.github.io/helm-charts`
3. 返回到 **扩展** 并安装 **VergeOS 节点驱动** 扩展

安装完成后， **VergeOS** 在创建集群时将作为节点驱动选项显示。

{% hint style="info" %}
**自签名证书**

如果 VergeOS 环境使用自签名证书，请在 Rancher 中创建云凭据时将 `insecure` 设置为 `true` 。这会告诉驱动在与 VergeOS API 通信时跳过 TLS 验证。
{% endhint %}

### 独立使用

该驱动也可以在 Rancher 之外直接与 Docker Machine 一起使用：

```bash
docker-machine create \
  --driver vergeos \
  --vergeos-host vergeos.example.com \
  --vergeos-api-key your-api-key \
  --vergeos-insecure \
  --vergeos-template-vm ubuntu-2404 \
  --vergeos-network your-network-name \
  --vergeos-ssh-user ubuntu \
  --vergeos-cpu-cores 2 \
  --vergeos-ram 4096 \
  --vergeos-disk-size 30 \
  my-docker-host
```

{% hint style="info" %}
**独立使用时需要 Docker**

当作为独立的 Docker Machine 驱动使用时（不通过 Rancher），模板虚拟机也需要安装 Docker，或者我们可以使用 `--vergeos-cloudinit` 在首次启动时安装它。
{% endhint %}

有关驱动标志和环境变量的完整列表，请参见 [文档和资源](#documentation-and-resources) 下方的驱动仓库。

{% hint style="info" %}
**SSH 用户默认值**

该驱动的 SSH 用户默认为 `root` ，但 Rancher UI 扩展默认为 `ubuntu`。直接使用 CLI 时，请设置 `--vergeos-ssh-user ubuntu` 用于 Ubuntu 模板。
{% endhint %}

***

## UI 扩展

该 UI 扩展向 Rancher 界面添加了 VergeOS 特定组件，在创建云凭据和配置机器时提供原生体验。

### 它添加了什么

**云凭据表单** ——提示填写：

* VergeOS 主机 URL
* API 密钥（存储为 Rancher secret）
* TLS 验证开关

**机器配置表单** ——提供：

* 模板虚拟机名称（要克隆的 VergeOS 虚拟机名称）
* 网络名称（要连接的 VergeOS VNet）
* CPU 核心数、内存和磁盘大小输入项
* cloud-init user-data 字段
* SSH 用户和端口配置

{% hint style="info" %}
**兼容性**

该 UI 扩展需要 Rancher v2.10+ 和 Rancher Extensions 框架 v3.x。
{% endhint %}

{% hint style="info" %}
**安装**

UI 扩展会作为 [组合 Helm chart](#installing-in-rancher)的一部分自动安装。无需单独的安装步骤。
{% endhint %}

***

## 总结

Rancher 集成由打包在单个 Helm chart 中的两个组件组成：

* **Docker Machine 驱动** ——克隆 VergeOS 模板虚拟机，并管理其生命周期以进行集群配置
* **UI 扩展** ——向 Rancher 界面添加 VergeOS 云凭据和机器配置表单

结合起来，它们使我们能够直接从 Rancher UI 在 VergeOS 基础设施上配置 RKE2/K3s 集群。一旦集群运行起来， [Kubernetes 集成](/automate-protect-and-extend/zh/ji-cheng-yu-api/kubernetes-integration.md) 组件会处理持久存储和节点生命周期。

## 后续步骤

* 在 VergeOS 中准备一个模板虚拟机（Ubuntu 24.04 + cloud-init + QEMU guest agent）
* 在 Rancher 集群中安装 [VergeOS 节点驱动](#installing-in-rancher) Helm chart
* 使用 **VergeOS** 作为节点驱动来配置下游集群
* 在 Rancher 集群中安装 [CSI 驱动和云控制器管理器](/automate-protect-and-extend/zh/ji-cheng-yu-api/kubernetes-integration.md) 在下游集群上用于持久存储和负载均衡器

## 文档和资源

有关详细配置、驱动标志、chart 值和发布说明，请参见 GitHub 仓库：

| 仓库                                                                                         | 描述                            |
| ------------------------------------------------------------------------------------------ | ----------------------------- |
| [docker-machine-driver-vergeos](https://github.com/verge-io/docker-machine-driver-vergeos) | Docker Machine / Rancher 节点驱动 |
| [ui-extension-vergeos](https://github.com/verge-io/ui-extension-vergeos)                   | Rancher UI 扩展                 |
| [helm-charts](https://github.com/verge-io/helm-charts)                                     | Helm chart 仓库                 |

## 支持

如果你遇到问题或有功能请求，请在相关的 GitHub 仓库中提交 issue：

<https://github.com/verge-io/docker-machine-driver-vergeos/issues>


---

# 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/automate-protect-and-extend/zh/ji-cheng-yu-api/rancher-integration.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.