> 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/kubernetes-integration.md).

# Kubernetes 集成

## 概述

VergeOS 通过 CSI 存储驱动和 Cloud Controller Manager（CCM）提供原生 Kubernetes 集成。这些组件将运行在 VergeOS VM 上的任何 Kubernetes 集群连接到基础 VergeOS 平台——无论是通过 [Rancher](/automate-protect-and-extend/zh/ji-cheng-yu-api/rancher-integration.md)、kubeadm 还是任何其他方式——部署的。

| 组件                                   | 用途                                      |
| ------------------------------------ | --------------------------------------- |
| [CSI 驱动](#csi-driver)                | 通过 VergeOS vSAN 为 Kubernetes Pod 提供持久存储 |
| [云控制器管理器](#cloud-controller-manager) | 节点生命周期和负载均衡器集成                          |

### 前提条件

* 运行在 VergeOS VM 上的 Kubernetes 集群（RKE2、K3s、kubeadm 等）
* VergeOS API 密钥（在用户设置中生成）
* `kubectl` 和 `helm` CLI 工具
* 可访问集群的 kubeconfig

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

如果 VergeOS 环境使用自签名证书，请在 Rancher 中创建云凭据时将 `vergeos.verifySSL=false` 在安装 CSI 驱动和 CCM Helm chart 时。这是默认设置，但如果我们之后更改它，值得注意。
{% endhint %}

***

## CSI 驱动

容器存储接口（CSI）驱动允许 Kubernetes Pod 申请并挂载 VergeOS 存储作为持久卷。它将存储操作直接委托给 VergeOS API，并利用 vSAN 发挥其设计用途——重复数据删除、多层级放置和分布式冗余。

### 存储后端

CSI 驱动支持两个后端，由一个 Go 二进制文件提供：

| 后端      | 访问模式          | 描述                                    |
| ------- | ------------- | ------------------------------------- |
| **NAS** | ReadWriteMany | 运行在 VergeOS NAS 服务上的 EXT4 卷，通过 NFS 暴露 |
| **块**   | ReadWriteOnce | 通过 vSAN 热插到 VergeOS VM 的虚拟机磁盘         |

{% hint style="info" %}
**为什么不是 Longhorn？**

Longhorn 运行自己的复制存储引擎 *在* Kubernetes 中，在虚拟化管理程序之上叠加复制、快照和调度。在 VergeOS 上，原生 CSI 驱动更适合：

* **无需双重复制** —— vSAN 的分布式镜像架构已经提供了数据冗余
* **内联重复数据删除** —— vSAN 去重在整个集群范围内全局生效；Longhorn 卷是不可解析的二进制块，无法参与
* **多层级放置** —— 卷会根据 StorageClass 落到正确的 vSAN 层级（NVMe、SSD、HDD）
* **统一管理** —— 卷会与 VM、快照和 NAS 共享一起出现在 VergeOS UI 中
  {% endhint %}

### 块存储池 VM

对于块存储，在 VergeOS 中创建一个名为 `k8spool`的空 VM。它永远不需要启动——只需保存空闲块磁盘即可。该 VM 的 ID 会在安装期间传递给 Helm chart。

### 安装

CSI 驱动以 Helm chart 的形式从 `verge-io` Helm 仓库发布，可通过 Helm CLI 或 **Rancher Apps UI** 在下游集群中安装。有关 chart 详情、Helm 值和配置选项，请参见 [文档和资源](#documentation-and-resources) 下文。

{% hint style="warning" %}
**下游集群**

通过 Rancher Apps UI 安装时，必须在 **下游集群**上添加 Helm 仓库，而不是在 Rancher 管理集群上。ClusterRepos 不会从管理集群传播。
{% endhint %}

***

## 云控制器管理器

Cloud Controller Manager（CCM）是 VergeOS 的标准 Kubernetes 云提供商接口。它负责节点生命周期管理和负载均衡器的配置。

### 功能

* **节点管理** —— 从 VergeOS VM 中填充 Kubernetes 节点元数据（provider ID、实例类型、内部 IP）。检测 VM 是否存在以及电源状态，以进行节点生命周期管理。
* **负载均衡** —— 为 `type: LoadBalancer` 类型服务配置 VergeOS VNet NAT/转换规则。自动从可配置池中分配 IP，并将服务端口映射到节点端口。

### 节点生命周期工作原理

CCM 实现 Kubernetes 的 `InstancesV2` 接口：

1. **InstanceMetadata** —— 将 Kubernetes 节点解析到一个 VergeOS VM（按 provider ID 或名称），然后返回 provider ID（`vergeos://<vm-id>`）、实例类型（`<cpu>cpu-<ram>mb`），以及来自 VM 网卡的内部 IP 地址
2. **InstanceExists** —— 检查底层 VM 是否仍然存在于 VergeOS 中
3. **InstanceShutdown** —— 报告 VM 是否已关闭电源

### 负载均衡工作原理

CCM 实现 Kubernetes 的 `LoadBalancer` 接口，使用 VergeOS VNet 规则：

1. **EnsureLoadBalancer** —— 从池中分配一个 IP，然后为每个服务端口创建一条 VNet NAT 规则。规则会转换 `<allocated-ip>:<port>` 设置为 `<node-ips>:<nodePort>`。调用 `ApplyRules` 以激活。
2. **UpdateLoadBalancer** —— 当节点变更时，更新现有规则上的目标 IP
3. **EnsureLoadBalancerDeleted** —— 删除该服务的所有 VNet 规则并应用更改

### 安装

CCM 与 CSI 驱动一起以 Helm chart 的形式发布。可通过 Helm CLI 或在下游集群上的 Rancher Apps UI 安装。有关 chart 详情和配置选项，请参见 [文档和资源](#documentation-and-resources) 下文。

***

## Cluster Autoscaler

Kubernetes Cluster Autoscaler 可与通过 [Rancher](/automate-protect-and-extend/zh/ji-cheng-yu-api/rancher-integration.md)部署的 VergeOS 后端集群一起工作。它会根据处于待定状态的 Pod 资源请求自动调整池中的节点数量——当 Pod 无法调度时扩容，当节点利用率不足时缩容。请参见 [文档和资源](#documentation-and-resources) 下文中的上游项目链接。

### 工作原理

自动伸缩器使用 Rancher 的 API 来管理节点池：

1. **扩容** —— 当 Pod 因资源不足而处于待定状态时，自动伸缩器会增加节点池大小。随后 Rancher 使用 Docker Machine 驱动来部署新的 VergeOS VM。
2. **缩容** —— 当节点在可配置时间内利用率不足时，自动伸缩器会对其进行封锁、驱逐并移除。驱动会删除底层的 VergeOS VM。

{% hint style="success" %}
**资源请求**

自动伸缩器基于 Pod 的资源请求而非实际使用情况做出伸缩决策。请确保工作负载在其 Pod 规格中定义了 `requests` ，以获得准确的伸缩行为。
{% endhint %}

***

## 总结

VergeOS 提供三个可与运行在 VergeOS VM 上的任何集群协同工作的 Kubernetes 组件：

* **CSI 驱动** —— 通过 VergeOS NAS（ReadWriteMany）和 vSAN 块存储（ReadWriteOnce）提供持久卷
* **云控制器管理器** —— 节点生命周期管理和 `LoadBalancer` 由 VergeOS VNet 规则支持的服务
* **Cluster Autoscaler** —— 为 Rancher 部署的集群自动进行节点池扩缩容

所有组件都以 Helm chart 的形式从 `verge-io` 仓库发布，并可通过 Helm CLI 或 Rancher Apps UI 安装。

## 后续步骤

* 刚开始在 VergeOS 上使用 Rancher？请参阅 [Rancher 集成](/automate-protect-and-extend/zh/ji-cheng-yu-api/rancher-integration.md) 指南，了解集群部署、模板 VM 准备和节点驱动设置。
* 已经有运行中的集群？添加 Helm 仓库并浏览可用 chart：

  ```bash
  helm repo add verge-io https://verge-io.github.io/helm-charts
  helm repo update
  helm search repo verge-io
  ```
* 访问下方项目仓库，获取 chart 值、配置参考和发行说明。

## 文档和资源

| 仓库                                                                                               | 描述            |
| ------------------------------------------------------------------------------------------------ | ------------- |
| [csi-vergeos](https://github.com/verge-io/csi-vergeos)                                           | 容器存储接口驱动      |
| [vergeos-cloud-controller-manager](https://github.com/verge-io/vergeos-cloud-controller-manager) | 云控制器管理器       |
| [helm-charts](https://github.com/verge-io/helm-charts)                                           | Helm chart 仓库 |
| [Kubernetes 集群自动伸缩器](https://github.com/kubernetes/autoscaler/tree/master/cluster-autoscaler)    | 上游集群自动伸缩器     |

## 支持

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

* [CSI 驱动问题](https://github.com/verge-io/csi-vergeos/issues)
* [CCM 问题](https://github.com/verge-io/vergeos-cloud-controller-manager/issues)
* [Helm Charts 问题](https://github.com/verge-io/helm-charts/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/kubernetes-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.