{"id":37998827,"url":"https://github.com/turtacn/open-vcluster-api","last_synced_at":"2026-01-16T19:01:23.349Z","repository":{"id":328293736,"uuid":"1114939305","full_name":"turtacn/open-vcluster-api","owner":"turtacn","description":"open-vcluster-api is an open-source project that provides a VM-like API for managing vcluster (virtual Kubernetes clusters).","archived":false,"fork":false,"pushed_at":"2025-12-12T06:40:32.000Z","size":42,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-12-13T15:45:16.210Z","etag":null,"topics":["kubernetes","kubernetes-cluster","vc","vcluster"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/turtacn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-12T05:31:39.000Z","updated_at":"2025-12-12T06:40:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/turtacn/open-vcluster-api","commit_stats":null,"previous_names":["turtacn/open-vcluster-api"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/turtacn/open-vcluster-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turtacn%2Fopen-vcluster-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turtacn%2Fopen-vcluster-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turtacn%2Fopen-vcluster-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turtacn%2Fopen-vcluster-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/turtacn","download_url":"https://codeload.github.com/turtacn/open-vcluster-api/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turtacn%2Fopen-vcluster-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28481364,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["kubernetes","kubernetes-cluster","vc","vcluster"],"created_at":"2026-01-16T19:01:22.139Z","updated_at":"2026-01-16T19:01:23.307Z","avatar_url":"https://github.com/turtacn.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🚀 open-vcluster-api\n\n**A VM-like API for Managing Virtual Kubernetes Clusters**\n\n[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Go Version](https://img.shields.io/badge/Go-1.21+-00ADD8?logo=go)](https://golang.org/)\n[![Protobuf](https://img.shields.io/badge/Protobuf-v3-blue)](https://protobuf.dev/)\n[![vcluster](https://img.shields.io/badge/vcluster-compatible-green)](https://www.vcluster.com/)\n\n[English](#english) | [中文](#中文) | [QuickStart](QuickStart.md) | [RoadMap](ROADMAP.md)\n\n\u003c/div\u003e\n\n---\n\n\u003ca name=\"english\"\u003e\u003c/a\u003e\n\n## 🌍 English\n\n### What is open-vcluster-api?\n\n**open-vcluster-api** is an open-source project that provides a **VM-like API** for managing [vcluster](https://www.vcluster.com/) (virtual Kubernetes clusters). It bridges the gap between traditional IaaS/VM management paradigms and cloud-native virtual cluster orchestration.\n\nUsers familiar with Virtual Machine lifecycle management can adopt vcluster with minimal learning curve, while still leveraging vcluster's unique capabilities.\n\n### Design Goals\n\n1. **Familiar Semantics**: Provide API operations that mirror VM lifecycle management (Create, Start, Stop, Snapshot, Restore)\n2. **VCluster-Native**: All resources and operations are named around `VCluster`, not `VM` or `Instance`\n3. **Extended Capabilities**: Expose vcluster-specific operations like `SuspendVCluster`, `ResumeVCluster`, `SnapshotVCluster`, and `RestoreVCluster`\n4. **Cloud-Native Architecture**: gRPC-first API design with Protobuf IDL, suitable for Kubernetes-native environments\n5. **Multi-Language Support**: Auto-generated SDKs for Go, TypeScript, and Python\n\n### VM-like but VCluster-Native\n\nWhile the API feels familiar to VM users, it respects vcluster's true nature:\n\n| VM Concept | VCluster Equivalent | Key Difference |\n|------------|---------------------|----------------|\n| Power Off | `SuspendVCluster` | Scales down control-plane pods, optionally drains workloads |\n| Power On | `ResumeVCluster` | Restores control-plane pods and reconciles workloads |\n| Snapshot | `SnapshotVCluster` | Captures etcd state + metadata, not disk image |\n| Resize | `ScaleVCluster` | Adjusts resource quotas and control-plane resources |\n\n### Architecture\n\n```mermaid\ngraph TB\n    %% 图例说明\n    subgraph Legend[图例（Legend）]\n        L1[用户接口（User Interface）]\n        L2[API层（API Layer）]\n        L3[控制层（Control Layer）]\n        L4[基础设施（Infrastructure）]\n    end\n\n    subgraph UI[用户接口（User Interface）]\n        Portal[管理门户（Portal）]\n        CLI[命令行工具（CLI）]\n        SDK[多语言SDK（SDKs）]\n    end\n\n    subgraph API[API网关层（API Gateway Layer）]\n        GW[API网关（Gateway）]\n        Auth[认证授权（Auth）]\n    end\n\n    subgraph SVC[核心服务层（Core Service Layer）]\n        VCS[VClusterService\u003cbr/\u003e虚拟集群服务]\n        SNS[SnapshotService\u003cbr/\u003e快照服务]\n        MON[MonitorService\u003cbr/\u003e监控服务]\n    end\n\n    subgraph CTL[控制器层（Controller Layer）]\n        Adapter[VCluster适配器（Adapter）]\n        Reconciler[状态协调器（Reconciler）]\n    end\n\n    subgraph INFRA[基础设施层（Infrastructure）]\n        HostK8s[宿主Kubernetes集群（Host K8s）]\n        VClusterPods[vcluster控制面Pods]\n        Storage[持久化存储（Storage）]\n    end\n\n    Portal --\u003e GW\n    CLI --\u003e GW\n    SDK --\u003e GW\n    GW --\u003e Auth\n    Auth --\u003e VCS\n    Auth --\u003e SNS\n    Auth --\u003e MON\n    VCS --\u003e Adapter\n    SNS --\u003e Adapter\n    Adapter --\u003e Reconciler\n    Reconciler --\u003e HostK8s\n    HostK8s --\u003e VClusterPods\n    VClusterPods --\u003e Storage\n````\n\n### Quick Start\n\nPlease refer to [QuickStart.md](QuickStart.md) for detailed instructions on how to build, test, and run the project.\n\n#### Prerequisites\n\n* Go 1.21+\n* Protocol Buffers compiler (`protoc`)\n* Buf CLI (optional, for easier builds)\n\n#### Generate Go Client/Server\n\n```bash\n# Clone the repository\ngit clone https://github.com/turtacn/open-vcluster-api.git\ncd open-vcluster-api\n\n# Generate code\nmake generate\n```\n\n#### Run Examples\n\n```bash\n# Build examples\nmake build\n\n# Run all\nmake examples\n```\n\n### Core API Operations\n\n| Operation          | Description                                     |\n| ------------------ | ----------------------------------------------- |\n| `CreateVCluster`   | Create a new virtual Kubernetes cluster         |\n| `GetVCluster`      | Retrieve details of a specific vcluster         |\n| `ListVClusters`    | List all vclusters with pagination              |\n| `DeleteVCluster`   | Delete a vcluster                               |\n| `ScaleVCluster`    | Adjust resources allocated to a vcluster        |\n| `SuspendVCluster`  | Suspend a running vcluster (stop control-plane) |\n| `ResumeVCluster`   | Resume a suspended vcluster                     |\n| `SnapshotVCluster` | Create a point-in-time snapshot                 |\n| `RestoreVCluster`  | Restore from a snapshot                         |\n\n### Examples Directory\n\n| Example                        | Description                                               |\n| ------------------------------ | --------------------------------------------------------- |\n| `simple-client-go/`            | Basic Go gRPC client demonstrating API calls              |\n| `simple-server-go/`            | Minimal in-memory server implementation                   |\n| `vcluster-adapter-controller/` | Production-ready controller integrated with loft/vcluster |\n\n### Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### License\n\nThis project is licensed under the MIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n\u003ca name=\"中文\"\u003e\u003c/a\u003e\n\n## 🇨🇳 中文\n\n### 项目简介\n\n**open-vcluster-api** 是一个开源项目，为 [vcluster](https://www.vcluster.com/)（虚拟Kubernetes集群）提供**类虚拟机风格的API**。该项目弥合了传统IaaS/虚拟机管理范式与云原生虚拟集群编排之间的鸿沟。\n\n熟悉虚拟机生命周期管理的用户可以以最小的学习成本采用 vcluster，同时充分利用 vcluster 的独特能力。\n\n### 为什么要给 vcluster 设计 VM 风格 API？\n\n企业在进行云原生转型时，运维团队往往对虚拟机管理非常熟悉。通过提供类似VM的API语义，我们可以：\n\n1. **降低认知门槛**：运维人员可以用熟悉的概念理解 vcluster\n2. **平滑迁移路径**：从传统虚拟化平台迁移到 Kubernetes 多租户方案\n3. **统一管理体验**：在混合环境中提供一致的资源管理界面\n4. **保留云原生优势**：底层仍然是 Kubernetes 原生实现\n\n### 设计原则\n\n1. **语义熟悉性**：提供与VM生命周期管理类似的API操作（创建、启动、停止、快照、恢复）\n2. **VCluster原生**：所有资源和操作都围绕 `VCluster` 命名，不使用 `VM` 或 `Instance`\n3. **扩展能力**：暴露vcluster特有的操作，如 `SuspendVCluster`、`ResumeVCluster`、`SnapshotVCluster` 和 `RestoreVCluster`\n4. **云原生架构**：gRPC优先的API设计，使用Protobuf IDL，适合Kubernetes原生环境\n5. **多语言支持**：自动生成Go、TypeScript和Python的SDK\n\n### API核心概念\n\n```mermaid\nclassDiagram\n    class VCluster {\n        +string name\n        +string namespace\n        +VClusterSpec spec\n        +VClusterStatus status\n        +map~string,string~ labels\n        +Timestamp create_time\n        +Timestamp update_time\n    }\n\n    class VClusterSpec {\n        +string kubernetes_version\n        +ResourceRequirements resources\n        +int32 replicas\n        +NetworkConfig network\n        +StorageConfig storage\n        +bool enable_ha\n        +string distro\n    }\n\n    class VClusterStatus {\n        +Phase phase\n        +string message\n        +repeated Condition conditions\n        +string kubeconfig\n        +string api_server_endpoint\n        +ResourceUsage current_usage\n    }\n\n    class VClusterService {\n        \u003c\u003cinterface\u003e\u003e\n        +CreateVCluster（）\n        +GetVCluster（）\n        +ListVClusters（）\n        +DeleteVCluster（）\n        +ScaleVCluster（）\n        +SuspendVCluster（）\n        +ResumeVCluster（）\n        +SnapshotVCluster（）\n        +RestoreVCluster（）\n    }\n\n    VCluster *-- VClusterSpec : 包含（contains）\n    VCluster *-- VClusterStatus : 包含（contains）\n    VClusterService ..\u003e VCluster : 管理（manages）\n```\n\n### 架构图\n\n```mermaid\ngraph TB\n    %% 用户接入层\n    subgraph USER[用户接入层（User Access Layer）]\n        Portal[管理门户\u003cbr/\u003e（Portal）]\n        CLI[命令行工具\u003cbr/\u003e（CLI）]\n        SDK_GO[Go SDK]\n        SDK_TS[TypeScript SDK]\n        SDK_PY[Python SDK]\n    end\n\n    %% API网关层\n    subgraph GATEWAY[API网关层（API Gateway Layer）]\n        GW[gRPC网关\u003cbr/\u003e（gRPC Gateway）]\n        REST[REST转换器\u003cbr/\u003e（REST Translator）]\n        AUTH[认证授权模块\u003cbr/\u003e（Auth Module）]\n    end\n\n    %% 业务服务层\n    subgraph SERVICE[业务服务层（Business Service Layer）]\n        VCS[VCluster服务\u003cbr/\u003e（VClusterService）]\n        SNAP[快照服务\u003cbr/\u003e（SnapshotService）]\n        QUOTA[配额服务\u003cbr/\u003e（QuotaService）]\n    end\n\n    %% 适配器层\n    subgraph ADAPTER[适配器层（Adapter Layer）]\n        VC_ADAPTER[vcluster适配器\u003cbr/\u003e（vcluster Adapter）]\n        HELM[Helm客户端\u003cbr/\u003e（Helm Client）]\n        K8S_CLIENT[Kubernetes客户端\u003cbr/\u003e（K8s Client）]\n    end\n\n    %% 基础设施层\n    subgraph INFRA[基础设施层（Infrastructure Layer）]\n        HOST_K8S[宿主Kubernetes集群]\n        ETCD[etcd存储]\n        VC_PODS[vcluster控制面Pods]\n    end\n\n    %% 连接关系\n    Portal --\u003e GW\n    CLI --\u003e GW\n    SDK_GO --\u003e GW\n    SDK_TS --\u003e GW\n    SDK_PY --\u003e GW\n    \n    GW --\u003e REST\n    GW --\u003e AUTH\n    AUTH --\u003e VCS\n    AUTH --\u003e SNAP\n    AUTH --\u003e QUOTA\n    \n    VCS --\u003e VC_ADAPTER\n    SNAP --\u003e VC_ADAPTER\n    QUOTA --\u003e VC_ADAPTER\n    \n    VC_ADAPTER --\u003e HELM\n    VC_ADAPTER --\u003e K8S_CLIENT\n    HELM --\u003e HOST_K8S\n    K8S_CLIENT --\u003e HOST_K8S\n    HOST_K8S --\u003e VC_PODS\n    HOST_K8S --\u003e ETCD\n```\n\n### 快速开始\n\n#### 前置条件\n\n* Go 1.21+\n* Protocol Buffers 编译器（`protoc`）\n* Buf CLI（可选，用于简化构建）\n\n#### 生成Go客户端/服务端代码\n\n```bash\n# 克隆仓库\ngit clone https://github.com/turtacn/open-vcluster-api.git\ncd open-vcluster-api\n\n# 使用buf生成代码\ncd tools \u0026\u0026 buf generate\n\n# 或直接使用protoc\nprotoc --go_out=. --go-grpc_out=. api/proto/vcluster_api.proto\n```\n\n#### 生成多语言SDK\n\n```bash\n# 生成所有语言的SDK（Go、TypeScript、Python）\n./scripts/generate-sdk.sh all\n\n# 生成特定语言的SDK\n./scripts/generate-sdk.sh go\n./scripts/generate-sdk.sh typescript\n./scripts/generate-sdk.sh python\n```\n\n#### 运行示例服务端\n\n```bash\ncd examples/simple-server-go\ngo run main.go\n```\n\n#### 运行示例客户端\n\n```bash\ncd examples/simple-client-go\ngo run main.go\n```\n\n### 示例说明\n\n| 示例                             | 描述                      |\n| ------------------------------ | ----------------------- |\n| `simple-client-go/`            | 基础Go gRPC客户端，演示API调用    |\n| `simple-server-go/`            | 最小化的内存存储服务端实现           |\n| `vcluster-adapter-controller/` | 与loft/vcluster集成的生产级控制器 |\n\n### 如何贡献\n\n我们欢迎各种形式的贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解贡献指南。\n\n### 开源协议\n\n本项目采用 MIT 协议开源 - 详见 [LICENSE](LICENSE) 文件。\n\n---\n\n## 参考资料\n\n1. [vcluster Official Documentation](https://www.vcluster.com/docs/) - vcluster官方文档\n2. [Loft Labs GitHub](https://github.com/loft-sh/vcluster) - vcluster开源实现\n3. [gRPC Documentation](https://grpc.io/docs/) - gRPC官方文档\n4. [Protocol Buffers Language Guide](https://protobuf.dev/programming-guides/proto3/) - Protobuf v3语法指南\n5. [Kubernetes API Conventions](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md) - Kubernetes API设计规范\n6. [Buf Documentation](https://buf.build/docs/) - Buf工具链文档","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fturtacn%2Fopen-vcluster-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fturtacn%2Fopen-vcluster-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fturtacn%2Fopen-vcluster-api/lists"}