> 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/07-kubernetes-rancher.md). # Kubernetes 与 Rancher 集成 在 VergeOS 上运行 Kubernetes 不是附加组件——它是一个 **一流集成** 由四个专门构建的组件（Docker Machine Driver、Rancher UI Extension、Cloud Controller Manager 和 CSI Driver）构成，并可为由 Rancher 预置的集群提供可选的 Cluster Autoscaler，它们让 Rancher（以及任何 RKE2/K3s 部署）能够全面感知 VergeOS 的计算、存储和网络能力。与其把 VergeOS 当作一个“傻瓜式”的虚拟机宿主机，这些组件使 Kubernetes 能够通过原生 VergeOS API 来创建节点、挂载持久存储并创建负载均衡器——也就是驱动仪表板的同一组 API。 ## 前置条件 在安装该集成之前，请确保环境提供： * 一个 **Rancher Server** 安装（v2.10+），并具备 `kubectl` 以及 `helm` CLI 工具 * 一个 **模板虚拟机** 运行 Ubuntu 24.04，并已安装 cloud-init（建议同时安装 QEMU guest agent） * 一个 **VergeOS API 密钥** 在以下位置生成： **用户设置** * 一个目标 VergeOS 网络，并且 **启用 DHCP** ——驱动通过 QEMU guest agent 发现节点 IP，若没有 DHCP，克隆的虚拟机将无法获得地址 * 用于块存储持久化的一个空 VergeOS 虚拟机，名为 **`k8spool`** ，用于存放空闲块驱动器（其 VM ID 会在安装时传递给 CSI Helm chart；该虚拟机无需启动） ## 架构概览 VergeOS Kubernetes 集成由四个独立组件交付——Docker Machine Driver、Rancher UI Extension、Cloud Controller Manager 和 CSI Driver——每个组件负责技术栈中的一层，并且为由 Rancher 预置的集群提供可选的 Cluster Autoscaler： ```mermaid graph TB subgraph "Rancher 仪表板" UI["UI 扩展
(vergeos 面板)"] RC["云凭证 &
机器配置"] end subgraph "节点预置" DMD["Docker Machine Driver
(docker-machine-driver-vergeos)"] end subgraph "Kubernetes 集群" CCM["云控制器管理器
(vergeos-cloud-controller-manager)"] CSI["CSI Driver
(csi-vergeos)"] end subgraph "VergeOS 平台" API["VergeOS REST API"] VM["虚拟机与模板"] VSAN["vSAN / NAS 存储"] NET["虚拟网络"] end UI --> RC RC --> DMD DMD -->|"克隆模板,
注入 SSH 密钥"| API API --> VM CCM -->|"节点生命周期,
负载均衡器"| API API --> NET CSI -->|"持久卷"| API API --> VSAN ``` ### Docker Machine Driver 将 VergeOS 虚拟机作为 Kubernetes 节点进行预置——克隆模板、注入 SSH 密钥、调整磁盘大小并挂载网络。 ### Rancher UI 扩展 直接在 Rancher 仪表板中展示 VergeOS 特有的云凭证和机器配置面板。 ### 云控制器管理器 将 Kubernetes 节点状态与 VergeOS 虚拟机生命周期同步，并按需预置负载均衡服务。 ### CSI 驱动 将 VergeOS 的 vSAN/NAS/块存储映射为 Kubernetes PersistentVolumes，用于有状态工作负载。 所有四个组件（DMD、UI 扩展、CCM、CSI 驱动）都通过 **verge-io Helm 仓库**分发，确保版本一致并简化安装。Rancher 预置的集群还可使用可选的 **Cluster Autoscaler** 。 ## Docker Machine Driver 该 `docker-machine-driver-vergeos` 是该集成的基础。它教会 Docker Machine（以及 Rancher）如何在 VergeOS 上创建虚拟机——将 VergeOS 变成 RKE2 和 K3s 集群的一等节点预置器。 ### 工作方式 当 Rancher（或独立的 Docker Machine）请求一个新节点时，驱动会执行以下流程： 1. **克隆模板虚拟机** ——克隆一个预先构建好的 VergeOS 虚拟机模板（例如带有 cloud-init 的 Ubuntu 24.04）以创建新节点 2. **配置计算资源** ——根据集群规格设置 CPU 核心数和内存 3. **通过 cloud-init 注入 SSH 密钥** ——驱动生成一对 SSH 密钥，并通过 cloud-init 注入公钥，以实现安全、免密码访问 4. **调整主磁盘大小** ——如果集群所需存储超过模板提供的容量，驱动会扩展启动盘 5. **连接到目标网络** ——虚拟机连接到指定的 VergeOS 虚拟网络 6. **开机并等待 IP** ——驱动通过 QEMU guest agent（首选）或 DHCP 租约回退来监测 IP 地址 如果任何步骤失败，驱动会自动清理部分创建的虚拟机——不会留下孤儿资源。 ### 身份验证 该驱动使用 **API 密钥身份验证** 与 VergeOS REST API 通信。请在 VergeOS UI 的 **用户设置**下生成一个 API 密钥，然后通过 `--vergeos-api-key` 标志或 `VERGEOS_API_KEY` 环境变量提供。 ### 配置标志 | 标志 | 环境变量 | 默认值 | 说明 | | ----------------------- | --------------------- | ---------- | ------------------------ | | `--vergeos-host` | `VERGEOS_HOST` | *（必填）* | VergeOS 端点 URL | | `--vergeos-api-key` | `VERGEOS_API_KEY` | *（必填）* | 用于身份验证的 API 密钥 | | `--vergeos-insecure` | `VERGEOS_INSECURE` | `false` | 跳过 TLS 验证 | | `--vergeos-template-vm` | `VERGEOS_TEMPLATE_VM` | *（必填）* | 要克隆的模板虚拟机名称 | | `--vergeos-network` | `VERGEOS_NETWORK` | *（必填）* | 用于挂载的目标网络 | | `--vergeos-cpu-cores` | `VERGEOS_CPU_CORES` | `2` | 每个节点的 CPU 核心数 | | `--vergeos-ram` | `VERGEOS_RAM` | `2048` | 每个节点的内存（MB） | | `--vergeos-disk-size` | `VERGEOS_DISK_SIZE` | `0` （模板大小） | 以 MB 为单位的磁盘大小覆盖值 | | `--vergeos-ssh-user` | `VERGEOS_SSH_USER` | `root` | SSH 用户名 | | `--vergeos-ssh-port` | `VERGEOS_SSH_PORT` | `22` | SSH 端口 | | `--vergeos-cloudinit` | — | — | 自定义 cloud-init 配置（文件或内联） | ### 模板要求 你的虚拟机模板必须包含： * **Cloud-init** 已安装并启用——SSH 密钥注入和主机名配置所必需 * **QEMU guest agent** （推荐）——提供可靠的 IP 地址发现；若不可用，则回退到 NIC DHCP 租约 * **Docker** （仅限独立使用）——Rancher 部署会自动安装容器运行时 ### Ubuntu 24.04 支持 该驱动包含对 Ubuntu 24.04 特性的自动处理： * **Netplan DHCP 配置** 用于动态 `en*` 接口命名 * **Machine-ID 重新生成** 以确保每个克隆实例拥有唯一的 DHCP 标识符 * **清理陈旧的 DHCP 租约** 以防止模板继承导致的 IP 冲突 {% hint style="success" %} **Rancher 节点规格** Rancher 部署要求每个节点至少 **4 GB 内存** 。为保证生产稳定性，建议每个节点使用 **8 GB 内存** 。 {% endhint %} ### 独立使用 你也可以在 Rancher 之外使用该驱动进行临时的 Docker Machine 预置： ```bash docker-machine create --driver vergeos \\ --vergeos-host vergeos.example.com \\ --vergeos-api-key your-api-key \\ --vergeos-template-vm ubuntu-2404 \\ --vergeos-network my-k8s-network \\ --vergeos-ssh-user ubuntu \\ --vergeos-cpu-cores 4 \\ --vergeos-ram 8192 \\ k8s-worker-01 ``` {% hint style="info" %} **SSH 用户默认值** 该驱动默认使用 `root` 进行 SSH 登录，但 Ubuntu 云镜像不允许 root SSH 登录。当直接通过 CLI 操作 Ubuntu 模板时，请设置 `--vergeos-ssh-user ubuntu` （Rancher UI 扩展已默认使用 `ubuntu`). {% endhint %} ## Rancher UI 扩展 该 `ui-extension-vergeos` 将 VergeOS 特有的面板添加到 **Rancher 仪表板**中，从而在不离开 Rancher UI 的情况下，以原生体验管理基于 VergeOS 的 Kubernetes 集群。 ### 云凭证面板 在 Rancher 中创建新的 Cloud Credential 时，扩展会添加一个 **VergeOS** 提供商选项。请输入你的 VergeOS 主机 URL、API 密钥和 TLS 设置——Rancher 会安全地存储这些信息，并在后续所有节点预置操作中使用它们。 ### 机器配置面板 在为新集群定义节点池时，扩展会展示 VergeOS 特有的配置字段： * **模板虚拟机** ——从可用的 VergeOS 虚拟机模板中选择 * **网络** ——选择目标虚拟网络 * **CPU / 内存 / 磁盘** ——设置每个节点的计算资源 * **Cloud-init** ——提供自定义初始化脚本 该扩展作为 `vergeos-node-driver` Helm chart 的一部分进行部署，它将 Docker Machine Driver 和 UI Extension 捆绑在一起。 ## 云控制器管理器 该 `vergeos-cloud-controller-manager` （CCM）通过实现标准的 Kubernetes cloud-provider 接口，将 Kubernetes 集群操作与 VergeOS 控制平面连接起来。 ### 节点生命周期同步 CCM 会持续监控 Kubernetes 节点列表，并将其与 VergeOS 虚拟机状态同步： * **节点注册** ——当新节点加入集群时，CCM 会为其添加 VergeOS 特有的元数据（VM ID、网络、区域） * **节点移除** ——当 VergeOS 虚拟机被删除或关机时，CCM 会将对应的 Kubernetes 节点标记为不可用，并触发 Pod 重新调度 * **健康监控** ——定期检查确保 Kubernetes 节点状态反映真实的虚拟机健康状况 ### 负载均衡器预置 当创建类型为 `LoadBalancer` 的 Kubernetes Service 时，CCM 会通过 VergeOS 网络层预置负载均衡器： * 从配置的地址池中分配一个虚拟 IP * 配置后端节点端口之间的流量分发 * 更新该 Service 的 `status.loadBalancer.ingress` 为已分配的 IP VergeOS 通过 CCM 原生处理负载均衡器预置。 {% hint style="info" %} **来自 VMware？** 在 VergeOS 上，CCM 将节点生命周期管理和 `LoadBalancer` Service 预置合并为一个通过 Helm 安装的组件——无需再拼接单独的 cloud-provider、CSI/CPI 和负载均衡器插件。 {% endhint %} {% hint style="info" %} **来自 Nutanix？** VergeOS 通过 Rancher 与任何 RKE2/K3s 工具链协同工作，而不是提供专有的 Kubernetes 发行版——你可以选择上游 Kubernetes 版本，而 CCM 在其上提供原生的云提供商集成。 {% endhint %} ## CSI 驱动 该 `csi-vergeos` （容器存储接口）驱动通过标准 CSI 规范将 VergeOS 存储暴露给 Kubernetes 工作负载。 ### 存储后端 该 CSI 驱动支持两个后端，均由一个 Go 二进制文件提供： | 后端 | 访问模式 | 说明 | | ------- | ------------- | ----------------------------------- | | **NAS** | ReadWriteMany | 在 VergeOS NAS 服务上的 EXT4 卷，通过 NFS 暴露 | | **块** | ReadWriteOnce | 通过 vSAN 热插拔到 VergeOS 虚拟机的 VM 驱动器 | ### 工作方式 1. 开发者创建一个 `PersistentVolumeClaim` （PVC）在 Kubernetes 中 2. CSI 驱动与 VergeOS API 通信，以预置所请求的存储 3. 该存储会挂载到运行 Pod 的节点上，并挂载到指定路径 4. 在 Pod 删除时，CSI 驱动会根据回收策略处理卸载及（可选的）删除 ### StorageClass 示例 ```yaml apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: vergeos-block provisioner: csi.vergeos.com parameters: type: block reclaimPolicy: Delete volumeBindingMode: WaitForFirstConsumer ``` Kubernetes 管理员定义 `StorageClass` 资源，这些资源映射到 VergeOS 的存储后端。开发者随后可以在其 PVC 中引用这些类，而无需了解底层基础设施。 ## Helm Charts 该 `helm-charts` 仓库将所有 VergeOS Kubernetes 组件打包，以便简化部署。可用三个 chart： ### 可用 Chart | Chart | 组件 | 用途 | | ---------------------------------- | ----------------------------- | ------------------- | | `vergeos-node-driver` | Docker Machine Driver + UI 扩展 | 节点预置和 Rancher 仪表板集成 | | `vergeos-cloud-controller-manager` | CCM | 节点生命周期同步和负载均衡器预置 | | `vergeos-csi` | CSI 驱动 | 持久存储（NAS + 块） | ### 安装 添加 VergeOS Helm 仓库并安装这些 chart： ```bash # 添加 VergeOS Helm 仓库 helm repo add verge-io https://verge-io.github.io/helm-charts helm repo update # 搜索可用 chart helm search repo verge-io # 安装 Cloud Controller Manager helm install vergeos-ccm verge-io/vergeos-cloud-controller-manager \\ --namespace kube-system # 安装 CSI 驱动 helm install vergeos-csi verge-io/vergeos-csi \\ --namespace kube-system # 安装节点驱动 + UI 扩展（用于 Rancher） helm install vergeos-node-driver verge-io/vergeos-node-driver \\ --namespace cattle-system \\ --set "vergeosHosts={vergeos.example.com}" ``` 该 `vergeosHosts` 值是 Rancher 代理允许访问的 VergeOS 主机名白名单，且为必需项。请将 `vergeos.example.com` 替换为你的 VergeOS 环境主机名；若没有它，驱动将无法访问 VergeOS API。 ## 端到端部署流程 将这四个组件组合起来，以下是在 VergeOS 上通过 Rancher 部署 Kubernetes 集群的完整流程： ```mermaid flowchart LR A["1. 准备
VM 模板"] --> B["2. 注册
节点驱动"] B --> C["3. 创建云
凭证"] C --> D["4. 预置
集群"] D --> E["5. 部署
CCM + CSI"] E --> F["6. 运行
工作负载"] style A fill:#2563eb,color:#fff style B fill:#2563eb,color:#fff style C fill:#2563eb,color:#fff style D fill:#2563eb,color:#fff style E fill:#2563eb,color:#fff style F fill:#16a34a,color:#fff ``` ### 步骤 1：准备 VM 模板 创建一个带有 Ubuntu 24.04（Noble Numbat）的 VergeOS 虚拟机——当前唯一受支持的模板操作系统——安装 cloud-init 和 QEMU guest agent，然后将其保存为模板。此模板将被用于克隆每个 Kubernetes 节点。 ### 步骤 2：注册节点驱动 使用 `kubectl`将 VergeOS NodeDriver 清单应用到你的 Rancher 管理集群中。这会让 Rancher 了解 VergeOS Docker Machine Driver，并将其启用为一种预置选项。注册后重启 Rancher 以激活驱动架构。 ### 步骤 3：创建云凭证 在 Rancher UI 中，创建一个新的 **Cloud Credential** ，并使用 VergeOS 提供程序（由 UI 扩展添加）。输入你的 VergeOS 主机 URL 和 API 密钥。 ### 步骤 4：预置集群 在 Rancher 中创建一个新的 RKE2 或 K3s 集群，并选择 VergeOS 作为基础设施提供商。使用所需的计算资源定义节点池（控制平面、etcd、工作节点）。Rancher 使用 Docker Machine Driver 克隆虚拟机、注入 SSH 密钥并引导 Kubernetes 集群。 ### 步骤 5：部署 CCM 和 CSI 通过 Helm 将 Cloud Controller Manager 和 CSI Driver 安装到新集群中。CCM 会立即开始与 VergeOS 同步节点状态，而 CSI 驱动会为 PersistentVolumeClaims 提供 VergeOS 存储。 ### 步骤 6：运行工作负载 使用标准 Kubernetes 清单部署你的应用。类型为 `LoadBalancer` 的 Service 由 CCM 处理，而 PersistentVolumeClaims 由 CSI 驱动提供——全部由 VergeOS 基础设施支撑。 ## 在 Rancher 中注册节点驱动 Docker Machine Driver 必须作为 Rancher NodeDriver 资源注册。请使用以下清单应用 `kubectl`: ```yaml apiVersion: management.cattle.io/v3 kind: NodeDriver metadata: name: vergeos annotations: privateCredentialFields: "apiKey" publicCredentialFields: "host,insecure" spec: active: true builtin: false displayName: vergeos uiUrl: "" url: "https://github.com/verge-io/docker-machine-driver-vergeos/releases/download/v0.1.0/docker-machine-driver-vergeos-linux-amd64.tar.gz" ``` 应用后，重启 Rancher 以加载新的驱动架构。随后，VergeOS 选项将出现在集群创建向导中。 ## 摘要 VergeOS Kubernetes 集成将 VergeOS 从一个 VM 平台转变为一个 **完整的 Kubernetes 云提供商**。通过实现 Docker Machine、Cloud Controller Manager 和 CSI 接口，VergeOS 为 Kubernetes 提供了与公有云提供商相同的基础能力——自动化节点部署、生命周期管理、负载均衡和持久存储——所有这些都运行在您自己的基础设施上，并具备 VergeOS vSAN 和虚拟网络的性能与效率。 ### 自动化节点部署 Docker Machine 驱动程序通过 cloud-init、SSH 密钥和网络连接从模板克隆虚拟机——并可通过 Rancher 完全自动化。 ### 原生云提供商 CCM 和 CSI 驱动实现了标准的 Kubernetes 接口，因此工作负载使用 `LoadBalancer` 服务和 `PersistentVolumeClaims` 无需修改。 ### Helm 管理式部署 所有组件都打包为 Helm chart，以便在各集群中进行一致、受版本控制的安装。 ### Rancher 原生体验 UI 扩展将 VergeOS 配置直接带入 Rancher 仪表板——无需切换上下文。 --- # 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/07-kubernetes-rancher.md?ask=&goal= ``` `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.