vCluster Platform

一个强大的Kubernetes平台，用于管理虚拟集群、多租户和集群共享

vCluster Platform提供单一管理界面，让您能够连接集群、部署虚拟集群、配置用户访问并降低运营成本。它构建在Kubernetes之上，使团队能够高效共享集群资源，同时保持强大的隔离性和自助服务能力。

🚀 功能

核心平台功能

• 项目：最高级别的组织单元，用于按团队或部门对资源进行逻辑分组，并配备基于角色的访问控制（RBAC）
• 集群：连接并管理多个物理Kubernetes集群，根据需要部署空间、虚拟集群和应用
• 虚拟集群：轻量级虚拟Kubernetes集群，运行在主机物理集群内的命名空间中——非常适合开发、测试和生产工作负载
• 应用：使用Kubernetes清单、bash脚本、Helm图表等，跨集群、空间和虚拟集群定义和部署具有可配置参数的应用
• 成本降低工具：
  • 睡眠模式：将Kubernetes命名空间置于睡眠状态（将所有副本控制资源的replicas: 0），最多可降低70%的云成本
  • 自动删除：为非活动虚拟集群配置自动删除
  • 非活动检测：自动检测命名空间非活动状态并做出响应
• 多租户：在项目、空间和虚拟集群级别提供细粒度RBAC
• GitOps就绪：所有资源均定义为自定义资源定义（CRD），支持GitOps工作流
• RESTful API：全面的OpenAPI 3.0兼容API，支持编程访问和自动化

📋 目录

• 快速开始
• 架构
• 安装与配置
• API文档
• Helm图表
• 配置
• 自动同步
• 测试
• 贡献
• 许可证
• 资源
• 支持
• 后续步骤

🏃 快速开始

前提条件

• Kubernetes集群（v1.20+），具有管理员访问权限
• 已安装Helm v3.10+（Helm Installation Guide）
• 已安装并配置kubectl（Install kubectl）
• 许可证密钥：需要LoftLabs许可证密钥（联系***获取许可证或试用版）

资源要求

• Pod资源：
  • 请求：内存：256Mi，CPU：200m memory: 256Mi cpu: 200m
  • 限制：内存：4Gi，CPU：2 memory: 4Gi cpu: 2
• 网络端口：确保以下端口已开放：
  • 8443 – 用于集群通信的API服务扩展（v1.cluster.loft.sh） 8443 v1.cluster.loft.sh
  • 9443 – Webhook验证和执行（loft webhook） 9443 loft webhook
  • 9444 – 用于平台管理的管理API（v1.management.loft.sh） 9444 v1.management.loft.sh
  • 9090 – 用于成本监控的Prometheus指标代理 9090
• 出口流量：允许出口到https://admin.loft.sh/*（HTTPS，端口443）以进行许可证检索和验证

安装方法

选项1：使用vCluster CLI（推荐）

vCluster CLI是部署平台的首选方法。详见快速开始指南。

# 下载并安装vCluster CLI
# macOS（Intel/AMD）
curl -L -o vcluster "https://github.com/loft-sh/vcluster/releases/latest/download/vcluster-darwin-amd64" && \
sudo install -c -m 0755 vcluster /usr/local/bin && rm -f vcluster

# 验证安装
vcluster --version

# 部署平台
vcluster platform start

CLI会自动在浏览器中打开UI并登录。系统将提示您创建管理员用户。

选项2：使用Helm

详见Helm安装指南。

# 添加Loft Helm仓库
helm repo add loft https://charts.loft.sh
helm repo update

# 部署vCluster Platform
RELEASE_NAME=vcluster-platform
RELEASE_NAMESPACE=vcluster-platform

helm upgrade $RELEASE_NAME vcluster-platform \
--install \
--repo https://charts.loft.sh/ \
--namespace $RELEASE_NAMESPACE \
--create-namespace \
--set admin.username=admin \
--set admin.password=your-secure-password

选项3：使用ArgoCD（GitOps）

对于GitOps部署，详见ArgoCD安装指南，了解如何使用ArgoCD或其他GitOps工具管理平台部署。

访问平台

安装后，您可以通过以下几种方式访问平台：

• Loft Router（默认）：如果未配置loftHost，将自动生成随机域名。使用以下命令获取：

kubectl get secret loft-router-domain \
-n vcluster-platform \
-o jsonpath="{.data.domain}" | base64 --decode

• 自定义Ingress：如果配置了Ingress，通过自定义域名访问

• 端口转发：本地访问：

kubectl port-forward -n vcluster-platform svc/vcluster-platform 8080:80

默认凭据

如果未在values.yaml中设置，默认凭据为：

• 用户名：admin
• 密码：my-password

[!WARNING] 安全注意事项：强烈建议首次登录后立即更改这些默认凭据。

📚 API 文档

vCluster Platform 公开了全面的 RESTful API，完全符合 OpenAPI 3.0 规范。API 文档会自动生成并同步到此仓库。

API 规范

• OpenAPI 规范：api/openapi-spec/openapi.yaml
• Swagger JSON：api/openapi-spec/swagger.json
• Swagger 路径：api/openapi-spec/swagger.paths.json

API 端点

API 提供以下端点：

• 管理 API（/apis/management.loft.sh/v1/）：核心平台管理操作
• 集群 API（/apis/v1.cluster.loft.sh/）：集群通信和管理
• 虚拟集群 API：虚拟集群生命周期管理
• 项目 API：项目和资源管理
• 用户与访问 API：用户管理和访问控制

使用 API

# 获取 API 版本
curl https://your-vcluster-platform/api/apis/

# 列出虚拟集群
curl -H "Authorization: Bearer $TOKEN" \

完整的 API 参考，请参见官方文档中的 API 文档。

📊 Helm 图表

vCluster Platform 的 Helm 图表会自动同步到此仓库。该图表包含：

• Deployment：主平台控制器和 API 服务器
• Service：用于访问平台的 Kubernetes 服务
• Ingress：可选的 ingress 配置，支持 TLS
• RBAC：服务账户、角色和角色绑定
• Webhooks：用于资源管理的验证和变异 webhook
• Certificates：集成 cert-manager 的 TLS 证书管理
• Monitoring：用于 Prometheus 集成的 ServiceMonitor
• Pod Disruption Budget：高可用性配置
• Persistent Volume Claims：平台数据的可选持久化

图表结构

chart/
├── Chart.yaml # 图表元数据
├── values.yaml # 默认配置值
├── templates/ # Kubernetes 清单
│ ├── deployment.yaml
│ ├── service.yaml
│ ├── ingress.yaml
│ ├── ingress-wakeup-service.yaml
│ ├── rbac/
│ │ └── clusterrolebinding.yaml
│ ├── webhook.yaml
│ ├── apiservice.yaml
│ ├── servicemonitor.yaml
│ ├── pdb.yaml
│ ├── pvc.yaml
│ ├── secret.yaml
│ ├── serviceaccount.yaml
│ └── cert-issuer/
│ └── issuer.yaml
└── tests/ # 图表测试
├── deployment_test.yaml
├── pdb_test.yaml
└── secret_test.yaml

查找图表版本

要检索平台 Helm 图表的所有可用版本：

helm search repo loft/vcluster-platform --versions

自定义安装

您可以通过创建自定义 values 文件来自定义安装：

# custom-values.yaml
admin:
username: myadmin
password: mypassword

config:
loftHost: vcluster-platform.example.com
audit:
enabled: true

ingress:
enabled: true
host: vcluster-platform.example.com
tls:
enabled: true

resources:
limits:
memory: 8Gi
cpu: "4"

然后使用以下命令安装：

helm upgrade vcluster-platform vcluster-platform \
--install \
--repo https://charts.loft.sh/ \
--namespace vcluster-platform \
--create-namespace \
--values custom-values.yaml

[!NOTE] vCluster Platform 仅支持默认的 secret 后端来存储 Helm 发布版本。不支持其他 HELM_DRIVER 配置（如 configmap 或 sql）。

[!NOTE] vCluster Platform 仅支持默认的 secret 后端来存储 Helm 发布版本。不支持其他 HELM_DRIVER 配置（如 configmap 或 sql）。

禁用 Loft Router

DISABLE_LOFT_ROUTER: "true"

GitOps 部署

vCluster Platform 可通过 ArgoCD 等 GitOps 工具进行管理。导出您的 Helm 配置并将其存储在 Git 仓库中，以实现版本控制的部署。

🔄 自动同步

本仓库会自动同步以下内容：

• API 文档：OpenAPI 规范会自动生成和更新
• Helm 图表：图表模板和值会与平台版本保持同步
• Swagger 规范：Swagger JSON 和路径定义会在更新时重新生成

这些组件会自动维护，确保仓库始终反映平台的最新功能。

🧪 测试

Helm 图表包含可执行的测试模板：

# 运行图表测试
helm test vcluster-platform -n vcluster-platform

🤝 贡献指南

欢迎贡献！详情请参见我们的贡献指南，其中包括：

• 行为准则
• 开发环境设置
• 拉取请求流程
• 问题报告

📄 许可证

详情请参见 LICENSE 文件。

🔗 资源

• 官方文档：vCluster Platform Docs
• 安装指南：快速入门指南 (CLI)、使用 Helm、使用 ArgoCD (GitOps)、离线安装
• 快速入门指南 (CLI)
• 使用 Helm
• 使用 ArgoCD (GitOps)
• 离线安装
• API 参考：参见 api/openapi-spec/ 目录或使用 API 文档 api/openapi-spec/
• Helm 图表：参见 chart/ 目录或 GitHub 仓库 chart/
• 配置参考：配置选项