kom

kom is a tool for Kubernetes operations, equivalent to an SDK-level wrapper for using kubectl and client-go. It provides a series of features to manage Kubernetes resources, including creating, updating, deleting, and getting resources, and even using SQL to query k8s resources. This project supports operations on multiple Kubernetes resource types and can handle custom resource definitions (CRDs). By using kom, you can easily perform CRUD operations on resources, retrieve logs, and manipulate files inside Pods.

Main capabilities:

• Simple and easy to use: provides create, update, delete, get, list, and other functions, including operations on built-in resources as well as CRD resources.
• Multi-cluster support: manage multiple Kubernetes clusters through RegisterCluster, and support AWS EKS clusters.
• MCP support: supports MCP management for multiple clusters, and also supports both stdio and sse modes, with 58 built-in tools, supports SSE mode, private deployment, multi-user sharing, and supports more than a hundred combined operations.
• Cross-namespace: query resources across namespaces through kom.Namespace("default","kube-system").List(&items).
• Chained calls: provides chained calls, making resource operations simpler and more intuitive.
• Supports custom resource definitions (CRDs): can easily define and operate custom resources.
• Supports a callback mechanism, making it easy to extend business logic without being strongly coupled with k8s operations.
• Supports file operations inside Pods, allowing files to be uploaded, downloaded, and deleted.
• Supports encapsulation of high-frequency operations, such as deployment restart, scale, start/stop, and more than 20 other operation functions.
• Supports SQL queries on k8s resources, for example select * from pod where metadata.namespace='kube-system' or metadata.namespace='default' order by metadata.creationTimestamp desc.
• Supports query caching. In high-frequency and batch query scenarios, a cache expiration time can be set to improve query performance, and list filter conditions are not affected by the cache.
• Supports Prometheus queries, supporting through the integratedPrometheus service in the cluster or an external Prometheus address for monitoring data queries, supporting instant queries and range queries, and providing multiple result parsing methods.

Usage: kom itself is used as an SDK, and also provides k8m, a lightweight Kubernetes management tool based on kom and amis, as a single file, supporting multiple platform architectures. Download: from https://github.com/weibaohui/k8m download the latest version. Run: use the ./k8m command to start, visit http://127.0.0.1:3618。

MCP integration: Supports integration in two ways, stdio and sse, suitable for MCP tool integration, such as Cursor, Claude Desktop (only supports stdio mode), Windsurf, etc. These software UI operation interfaces can also be used to add it.

• Add the MCP Server address in the API configuration area of the Claude Desktop settings panel.
• For the sse method, fill in http://localhost:9096/sse，stdio method, fill in the file location of kom. Managing k8s by default uses the KUBECONFIG environment variable. The compiled binary file can be used as stdio mode,http://IP:9096/sse Can be used as SSE mode.

AWS EKS cluster registration instructions:

• AccessKey: AWS access key ID
• SecretAccessKey: AWS secret access key
• Region: AWS region, such as us-east-1, ap-southeast-1, etc.
• ClusterName: EKS cluster name
• RoleARN: (optional) the ARN of the IAM role to assume, used for cross-account access After cluster registration, an ID will be generated automatically in the format {Region}-{ClusterName}, supporting the IAM role assumption mechanism for cross-account cluster access. AWS credential information is used only in memory and is automatically cleared after the program restarts.

Resource operation examples:

• CRUD and Watch of built-in resource objects: define a Deployment object and perform resource operations through kom.
• YAML create, update, delete.
• Execute commands inside a Pod: the container name must be specified, and Exec()-type callbacks will be triggered; StreamExec()-type callbacks are suitable for executing commands such as ping; execute the env command inside a Pod to obtain ENV configuration information; extract ENV configuration information from the pod definition.
• Based on configuration information such as NodeSelector, NodeAffinity, taint tolerations, and NodeName declared in the Pod definition, return the list of available nodes. Pod affinity, CPU, memory, and other runtime scheduling factors are not currently considered.

CRD operations: Even without a CR definition, CRUD operations can still be performed in the same way as for built-in k8s resources. Define the object as unstructured.Unstructured, and specify Group, Version, and Kind. You can use kom.DefaultCluster().GVK(group, version, kind) instead of kom.DefaultCluster().Resource(interface{}). For ease of memory and use, kom provides kom.DefaultCluster().CRD(group, version, kind) to simplify operations.

Callback mechanism: Built-in callback mechanism, you can customize callback functions. After a certain operation is executed, the corresponding callback function will be called. If the callback function returns true, subsequent operations will continue to be executed; otherwise, subsequent operations will be terminated. Currently supported callbacks include: get, list, create, update, patch, delete, exec, stream-exec, logs, watch, doc. The built-in callback names are: "kom:get","kom:list","kom:create","kom:update","kom:patch","kom:watch","kom:delete","kom:pod:exec","kom:pod:stream:exec","kom:pod:logs","kom:pod:port:forward","kom:doc". Callback sorting is supported; by default they are executed in registration order, and the order can be set through kom.DefaultCluster().Callback().After("kom:get") or .Before("kom:get"). Deleting callback functions is supported through kom.DefaultCluster().Callback().Delete("kom:get"); replacing callback functions is supported through kom.DefaultCluster().Callback().Replace("kom:get",cb).

SQL query: Query k8s resources through the SQL() method, which is simple and efficient. Table names support the full names and abbreviations of all resources registered in the cluster, including CRD resources. As long as it is registered on the cluster, it can be queried. Typical table names include: pod, deployment, service, ingress, pvc, pv, node, namespace, secret, configmap, serviceaccount, role, rolebinding, clusterrole, clusterrolebinding, crd, cr, hpa, daemonset, statefulset, job, cronjob, limitrange, horizontalpodautoscaler, poddisruptionbudget, networkpolicy, endpoints, ingressclass, mutatingwebhookconfiguration, validatingwebhookconfiguration, customresourcedefinition, storageclass, persistentvolumeclaim, persistentvolume, podsecurity, etc. The query fields currently only support *, i.e., select *. The query conditions currently support =, !=, >=, <=, <>, like, in, not in, and, or, between. The sorting field currently supports sorting by a single field, with the default being sorted in descending order by creation time. Setting a cache time is supported to avoid frequent queries to the k8s API. This includes the current request value, limit value, allocatable value, and usage ratio.

Prometheus query: kom provides powerful Prometheus query capabilities, supporting monitoring data queries through the Prometheus service within the cluster or an external Prometheus address.

• Automatically resolve the Prometheus service address within the cluster through the namespace and service name: WithInClusterEndpoint(namespace, svcName) automatically finds the Prometheus Service under the specified namespace, supports automatic recognition of the common port (9090) and port names (web, http, prometheus, metrics), and the generated address format is http://service-name.namespace.svc:port。
• Directly specify the Prometheus access address. kom provides multiple ways to parse Prometheus query results and provides convenient methods to directly obtain query results of a specific type.

Applicable scenarios: Suitable for developers who need to integrate Kubernetes operation capabilities in an SDK manner, DevOps scenarios that require multi-cluster management and CRD operations, scenarios that need to integrate k8s management capabilities into AI tools (such as Cursor, Claude Desktop, Windsurf) through MCP, and scenarios that require querying k8s resources in SQL or querying Prometheus monitoring data.

Limitations: SQL query fields currently only support *; sorting currently only supports a single field; the node list return does not take into account runtime scheduling factors such as Pod affinity, CPU, and memory. Other features, pricing, or platform information not explained in the materials are not currently provided.