How weibaohui/kom works
Project Type and Purpose
• Kom is a Kubernetes operations toolkit – in effect an SDK-level wrapper around client-go/kubectl. It supports CRUD operations, SQL-like queries on resources, multi-cluster & CRD management, and a callback mechanism for extending behavior.
• It’s a backend tool/library that can be used either as a standalone CLI utility or integrated into wider MCP (Multi-Cluster Processing) toolchains (e.g., k8m, Cursor, etc.).
Analyzing the File Structure
• Top-level directories and files such as “kom”, “mcp”, “callbacks”, “utils”, and “example” indicate a separation of concerns:
• The “kom” folder contains the core functionality (control operations, resource management, resource description, SQL query processing, and dynamic operations).
• The “mcp” folder contains the multi-cluster server aspects that expose endpoints (supporting both SSE and stdio) and include sub-tools that wrap various Kubernetes operations.
• The “callbacks” directory holds a set of functions that plug into various operations (get, list, create, update, etc.) to provide extensibility.
• “utils” provides common helper functions (caching, type conversion, network tools, etc.).
• “example” provides test cases and sample usage scenarios.
• Key configuration/build files (go.mod, .github/workflows) indicate that the project is built using Go and CI/CD is integrated.
• Client/CLI/Application Layer:
• Represents how users invoke Kom. This might be a CLI command (via main.go) or integration into tools that invoke Kom operations.
• Core Kom Engine:
• Represented by the “kom” module: includes resource controllers (e.g., Ctl() components such as ctl_cronjob, ctl_deploy, ctl_ds, etc.), SQL processing (sql.go, sql_builder.go, statement.go), dynamic operations, and description functions.
• Callback Manager:
• MCP Server (Multi-Cluster Management):
• Illustrated from the “mcp” directory. It supports starting an MCP server (via mcp/server.go) with endpoints (e.g., /sse) and integrating with external tools in sse or stdio modes.
• Cluster Registry and Multi-Cluster Support:
• A “Cluster Manager” component that registers multiple Kubernetes clusters. The methods in kom/cluster.go and related files register cluster configurations from the host’s kubeconfig or in-cluster settings.
• Kubernetes API Interaction:
• A component representing the external Kubernetes clusters (or their API servers), which the Kom engine communicates with to perform resource CRUD, watch, and SQL queries.
• Utility/Helper Module:
• Represented by “utils”, used across all layers to support type conversions, caching, computation of resource usage, etc.
Relationships and Data Flow
• Users (or external tools) invoke commands via the CLI or integrated UI.
• The invocation is handled by the Core Kom Engine. It passes through the Callback Manager as pre- and post-operation hooks.
• Operations (CRUD, patch, command execution, file manipulations) are then dispatched via “Ctl” methods in the “kom” module.
• For multi-cluster scenarios, the MCP Server oversees the registration and routing of commands to the appropriate registered clusters.
• SQL queries (via the specialized SQL processor in Kom) translate user queries into resource requests against Kubernetes API servers.
• The Engine uses utility functions (from “utils”) for additional processing (e.g., caching, JSON conversions, network interactions).