README_en.md

January 9, 2026 · View on GitHub

K8M

GitHub Repo Stars GitHub Repo Forks

GitHub Release GitHub Downloads (all assets, all releases) GitHub Repo Issues Repobeats analytics image

k8m is an AI-driven Mini Kubernetes AI Dashboard lightweight console tool designed to simplify cluster management. It is built on AMIS and uses kom as the Kubernetes API client. k8m comes with built-in Qwen2.5-Coder-7B, supports deepseek-ai/DeepSeek-R1-Distill-Qwen-7B model interaction capabilities, and supports integration with your own private AI models (including ollama).

Demo

DEMO DEMO-InCluster Mode Username and password demo/demo

Documentation

For detailed configuration and usage instructions, please refer to Documentation.
For changelog, please refer to Changelog.
For customizing AI model parameters and configuring private AI models, please refer to Self-Hosted/Custom AI Model Support and Ollama Configuration.
For detailed configuration option descriptions, please refer to Configuration Options.
For database configuration, please refer to Database Configuration.
DeepWiki documentation: Development Design Documentation

Key Features

Miniaturized Design: All functionalities are integrated into a single executable file for easy deployment and simple usage.
Easy to Use: Friendly user interface and intuitive operation workflow make Kubernetes management easier. Supports standard k8s, aws eks, k3s, kind, k0s and other cluster types.
High Performance: Backend built with Golang, frontend based on Baidu AMIS, ensuring high resource utilization and fast response speed.
AI-Driven Integration: Implements word explanation, resource guide, YAML attribute automatic translation, Describe information interpretation, log AI diagnosis, and running command recommendation based on ChatGPT, and integrates k8s-gpt functionality for Chinese display, providing intelligent support for managing k8s.
Feature Plugin: Feature functions are plugin-based, enabled on demand, no resource consumption when not enabled.
MCP Integration: Visual management of MCP, enabling large model calls to Tools, with 49 built-in k8s multi-cluster MCP tools that can be combined to achieve over a hundred cluster operations. Can serve as MCP Server for other large model software. Easily implement large model management of k8s. Can record every MCP call in detail. Supports mcp.so mainstream services.
MCP Permission Integration: Multi-cluster management permissions and MCP large model call permissions are integrated. In a nutshell: whoever uses the large model executes MCP with their permissions. Safe usage without worries, avoiding unauthorized operations.
Multi-Cluster Management: Automatically recognizes clusters using InCluster mode internally, automatically scans configuration files in the same directory after configuring kubeconfig path, and registers multiple clusters for management simultaneously. Supports heartbeat detection and automatic reconnection.
Multi-Cluster Permission Management: Supports authorization for users and user groups, can authorize by cluster, including cluster read-only, Exec command, and cluster administrator three types of permissions. After authorizing user groups, users in the group all get corresponding authorization. Supports setting namespace blacklist/whitelist.
Supports k8s Latest Features: Supports APIGateway, OpenKruise and other functional features.
Pod File Management: In the file tree on the left side of the Console interface, right-click menu supports browsing, editing, uploading, downloading, and deleting files within Pods, simplifying daily operations.
Pod Operation Management: Supports real-time viewing of Pod logs, downloading logs, and directly executing Shell commands within Pods. Supports Ctrl+F search, similar to grep -A -B highlighted search.
API Open: Supports creating API KEY for third-party external access, provides swagger interface management page.
Cluster Inspection Support: Supports multi-cluster scheduled inspection, custom inspection rules, supports lua script rules. Supports sending to DingTalk groups, WeChat groups, Feishu groups and custom webhooks. Supports AI summary.
k8s Event Forwarding: Supports multi-cluster k8s Event forwarding to webhooks, can filter by cluster, keywords, namespace, name, etc., establishing multiple dedicated monitoring forwarding channels. Supports AI summary.
CRD Management: Can automatically discover and manage CRD resources, list all CRDs in tree form, improving work efficiency.
Helm Marketplace: Supports free addition of Helm repositories, one-click installation, uninstallation, and upgrade of Helm applications, supports automatic updates.
Cross-Platform Support: Compatible with Linux, macOS and Windows, and supports x86, ARM and other architectures, ensuring seamless multi-platform operation.
Multi-Database Support: Supports SQLite, MySql, PostgreSql and other databases.
Fully Open Source: Opens all source code without any restrictions, can be freely customized and extended, and can be used commercially.

k8m's design philosophy is "AI-driven, lightweight and efficient, simplifying complexity," helping developers and operators quickly get started and effortlessly manage Kubernetes clusters.

Plugin System

k8m adopts a plugin-based architecture where all functional modules exist as plugins, supporting flexible enable/disable and extension. The plugin system provides complete lifecycle management, dependency resolution, scheduled task scheduling, and other features.

Plugin Features

Modular Design: Each plugin is independently developed, deployed, and managed without affecting each other
Lifecycle Management: Supports complete plugin lifecycle including installation, enable, disable, uninstall, start, stop, etc.
Dependency Management: Supports dependency declaration between plugins, automatically loads in order
Scheduled Tasks: Supports defining scheduled tasks in plugins using standard cron expressions
Route Registration: Supports multiple route types including cluster routes, management routes, plugin management routes, etc.
Database Management: Plugins can declare database tables they use, system manages automatically
Multi-Instance Support: Implements master-standby switching in multi-instance environments through election plugin

Built-in Plugin List

Plugin Name	Plugin Title	Version	Description
leader	Multi-Instance Election Plugin	1.0.0	Provides multi-instance automatic election capability: completes leader election through Kubernetes native mechanisms. Please ensure /health/ready readiness probe is enabled before use. After enabling, traffic will be concentrated on the master instance.
k8swatch	K8s Resource Monitoring Plugin	1.0.0	Monitors Kubernetes resource changes, including Pod, Node, PVC, PV, Ingress, etc. After disabling, real-time data on some pages will not be displayed.
webhook	Webhook Plugin	1.0.0	Webhook receiver management, test sending and sending record query
eventhandler	Event Forwarding Plugin	1.0.0	K8s event collection, rule filtering and Webhook forwarding. After enabling election plugin, only master instance executes, otherwise each instance executes.
inspection	Cluster Inspection Plugin	1.0.0	Lua-based cluster inspection plan, rule management and result viewing. After enabling election plugin, only master instance executes, otherwise each instance executes.
helm	Helm Management Plugin	1.0.0	Helm repository, Chart, Release management. Includes repository addition, Chart browsing, Release installation upgrade uninstallation and other functions. Scheduled update of repository index.
gllog	Global Log	1.0.0	Global log query, supports cross-cluster Pod log viewing
swagger	Swagger Documentation	1.0.0	Swagger API documentation viewing. Execute make.sh script in plugin directory to generate documentation.
mcp_runtime	MCP Runtime Management Plugin	1.0.0	Manages MCP servers used for large model conversations. Includes MCP server configuration, tool management, execution log viewing, open MCP service and other functions. When calling MCP in conversation, Authorization header will be automatically added with value JWT token.
openapi	OpenAPI Plugin	1.0.0	API key management for programmatic access to platform
k8m_mcp_server	K8M MCP Server Plugin	1.0.0	Uses K8M as MCP Server. Can be added to MCP runtime management for use. This plugin listens on /mcp/k8m/sse to provide service.
k8sgpt	K8sGPT Plugin	1.0.0	Kubernetes resource AI intelligent analysis, supports intelligent diagnosis of multiple resource types such as Pod, Deployment, Service, etc. Source from https://github.com/k8sgpt-ai/k8sgpt project
ai	AI Plugin	1.0.0	AI function plugin, provides K8s resource intelligent analysis, event consultation, log analysis, Cron expression parsing and other functions. Supports custom AI model configuration.
heartbeat	Cluster Heartbeat Reconnection Plugin	1.0.0	Manages cluster heartbeat detection and automatic reconnection function
gatewayapi	Gateway API Management Plugin	1.0.0	Kubernetes Gateway API management
istio	Istio Management Plugin	1.0.0	Kubernetes Istio service mesh management
openkruise	OpenKruise Management Plugin	1.0.0	Kubernetes OpenKruise advanced workload management
demo	Demo Plugin	1.0.12	Demonstrates fixed list and CRUD functionality

Plugin Development

For detailed plugin development documentation, please refer to: Plugin Architecture Documentation

Plugin development includes the following contents:

Plugin metadata definition
Lifecycle interface implementation
Route registration
Database table management
Scheduled task configuration
Menu declaration
Dependency relationship management

Run

Download: Download the latest version from GitHub release.
Run: Start with the ./k8m command and visit http://127.0.0.1:3618.
Login Username and Password:
- Username: k8m
- Password: k8m
- Please note to change username/password and enable two-factor authentication after going online.
Parameters:

Usage of ./k8m:
      --enable-temp-admin                Whether to enable temporary admin account configuration, disabled by default
      --admin-password string            Administrator password, takes effect after enabling temporary admin account configuration
      --admin-username string            Administrator username, takes effect after enabling temporary admin account configuration
      --print-config                     Whether to print configuration information (default false)
      --connect-cluster                  Whether to automatically connect to existing clusters when starting, disabled by default
  -d, --debug                            Debug mode
      --in-cluster                       Whether to automatically register and manage the host cluster, enabled by default
      --jwt-token-secret string          Secret used for generating JWT token after login (default "your-secret-key")
  -c, --kubeconfig string                Path to kubeconfig file (default "/root/.kube/config")
      --kubectl-shell-image string       Kubectl Shell image. Default is bitnami/kubectl:latest, must contain kubectl command (default "bitnami/kubectl:latest")
      --log-v int                        Log level for klog.klog.V(2) (default 2)
      --login-type string                Login method, password, oauth, token, etc., default is password (default "password")
      --image-pull-timeout               Node Shell, Kubectl Shell image pull timeout. Default is 30 seconds
      --node-shell-image string          NodeShell image. Default is alpine:latest, must contain `nsenter` command (default "alpine:latest")
  -p, --port int                         Listening port (default 3618)
  -v, --v Level                          Log level for klog (default 2)

You can also directly start it using docker-compose (recommended):

services:
  k8m:
    container_name: k8m
    image: registry.cn-hangzhou.aliyuncs.com/minik8m/k8m
    restart: always
    ports:
      - "3618:3618"
    environment:
      TZ: Asia/Shanghai
    volumes:
      - ./data:/app/data

After startup, access port 3618, default username: k8m, default password: k8m. If you want to quickly set up an experience through an online environment, you can visit: k8m

ChatGPT Configuration Guide

Built-in GPT

Starting from version v0.0.8, GPT is built-in and does not require configuration. If you need to use your own GPT, please refer to the following documentation.

Self-Hosted/Custom AI Model Support - How to use self-hosted models
Ollama Configuration - How to configure and use Ollama large models

ChatGPT Status Debugging

If setting parameters does not work, try using ./k8m -v 6 to get more debugging information. The following information will be output, check the logs to confirm whether ChatGPT is enabled.

ChatGPT enabled status:true
ChatGPT enabled key:sk-hl**********************************************, url:https://api.siliconflow.cn/v1
ChatGPT uses model set in environment variables:Qwen/Qwen2.5-7B-Instruc

ChatGPT Account

This project integrates the github.com/sashabaranov/go-openai SDK. For users in China, it's recommended to use the Silicon Flow service. After logging in, create an API_KEY at https://cloud.siliconflow.cn/account/ak

k8m Environment Variable Settings

k8m supports flexible configuration through environment variables and command line parameters. The main parameters are as follows:

Environment Variable	Default Value	Description
`PORT`	`3618`	Listening port number
`KUBECONFIG`	`~/.kube/config`	Path to `kubeconfig` file, automatically scans and identifies all configuration files in the same directory
`ANY_SELECT`	`"true"`	Whether to enable arbitrary selection word explanation, enabled by default (default true)
`LOGIN_TYPE`	`"password"`	Login method (e.g., `password`, `oauth`, `token`)
`ENABLE_TEMP_ADMIN`	`"false"`	Whether to enable temporary admin account configuration, disabled by default. Used for first login or forgotten password
`ADMIN_USERNAME`		Administrator username, takes effect after enabling temporary admin account configuration
`ADMIN_PASSWORD`		Administrator password, takes effect after enabling temporary admin account configuration
`DEBUG`	`"false"`	Whether to enable `debug` mode
`LOG_V`	`"2"`	Log output level, same usage as klog
`JWT_TOKEN_SECRET`	`"your-secret-key"`	Secret used for JWT Token generation
`KUBECTL_SHELL_IMAGE`	`bitnami/kubectl:latest`	kubectl shell image address
`NODE_SHELL_IMAGE`	`alpine:latest`	Node shell image address
`IMAGE_PULL_TIMEOUT`	`"30"`	Node shell, kubectl shell image pull timeout (seconds)
`CONNECT_CLUSTER`	`"false"`	Whether to automatically connect to discovered clusters after starting the program, disabled by default
`PRINT_CONFIG`	`"false"`	Whether to print configuration information

For detailed parameter description and more configuration methods, please refer to docs/readme.md.

These environment variables can be set when running the application, for example:

export PORT=8080
export GIN_MODE="release"
./k8m

For other parameters, please refer to docs/readme.md.

Running with Containerized k8s Cluster

Use KinD or MiniKube to install a small k8s cluster.

KinD Method

Create KinD Kubernetes Cluster

brew install kind

Create a new Kubernetes cluster:

kind create cluster --name k8sgpt-demo

Deploy k8m to the Cluster for Experience

Installation Script

kubectl apply -f https://raw.githubusercontent.com/weibaohui/k8m/refs/heads/main/deploy/k8m.yaml

Access: NodePort is used by default, please access port 31999. Or configure Ingress yourself. http://NodePortIP:31999

Modify Configuration

It is recommended to modify through environment variables first. For example, add env parameters in deploy.yaml.

Built-in MCP Server Guide

AI Tool Integration

General Configuration

Suitable for MCP tool integration like Cursor, Claude Desktop, Windsurf, etc. You can also use these software's UI to add configurations.

{
  "mcpServers": {
    "kom": {
      "type": "sse",
      "url": "http://IP:9096/sse"
    }
  }
}

Claude Desktop

Open Claude Desktop settings panel
Add MCP Server address in API configuration section
Enable SSE event listening
Verify connection status

Cursor

Enter Cursor settings interface
Find extension service configuration
Add MCP Server URL (e.g. http://localhost:3618/mcp/k8m/sse)

Windsurf

Access configuration center
Set API server address

MCP FAQ

Ensure MCP Server is running with accessible ports
Check network connectivity
Verify SSE connection establishment
Check tool logs for troubleshooting (failed MCP executions will have error records)

Service Endpoint, Can be Developed for Use by Other AI Tools

If started in binary mode, the access address is http://ip:3618/mcp/k8m/sse If started in cluster mode, the access address is http://nodeIP:31919/sse

Cluster Management Scope

The management scope of the built-in MCP Server is consistent with the cluster scope managed by k8m. All connected clusters in the interface can be used.

Built-in MCP Server Configuration Instructions

MCP Tool List (49 types)

Category	Method	Description
Cluster Management (1)	`list_clusters`	List all registered Kubernetes clusters
Deployment Management (12)	`scale_deployment`	Scale Deployment
	`restart_deployment`	Restart Deployment
	`stop_deployment`	Stop Deployment
	`restore_deployment`	Restore Deployment
	`update_tag_deployment`	Update Deployment image tag
	`rollout_history_deployment`	Query Deployment upgrade history
	`rollout_undo_deployment`	Rollback Deployment
	`rollout_pause_deployment`	Pause Deployment upgrade
	`rollout_resume_deployment`	Resume Deployment upgrade
	`rollout_status_deployment`	Query Deployment upgrade status
	`hpa_list_deployment`	Query HPA list of Deployment
	`list_deployment_pods`	Get Pod list managed by Deployment
Dynamic Resource Management (including CRD, 8)	`get_k8s_resource`	Get k8s resource
	`describe_k8s_resource`	Describe k8s resource
	`delete_k8s_resource`	Delete k8s resource
	`list_k8s_resource`	List k8s resources in list form
	`list_k8s_event`	List k8s events in list form
	`patch_k8s_resource`	Update k8s resource using JSON Patch
	`label_k8s_resource`	Add or delete labels for k8s resources
	`annotate_k8s_resource`	Add or delete annotations for k8s resources
Node Management (8)	`taint_node`	Add taint to node
	`untaint_node`	Remove taint from node
	`cordon_node`	Set Cordon for node
	`uncordon_node`	Cancel Cordon for node
	`drain_node`	Execute Drain for node
	`get_node_resource_usage`	Query resource usage of node
	`get_node_ip_usage`	Query Pod IP resource usage on node
	`get_node_pod_count`	Query Pod count on node
	`drain_node`	Execute Drain for node
	`get_node_resource_usage`	Query resource usage of node
	`get_node_ip_usage`	Query Pod IP resource usage on node
	`get_node_pod_count`	Query Pod count on node
Pod Management (14)	`list_pod_files`	List Pod files
	`list_all_pod_files`	List all Pod files
	`delete_pod_file`	Delete Pod file
	`upload_file_to_pod`	Upload file to Pod, supports passing text content and storing as Pod file
	`get_pod_logs`	Get Pod logs
	`run_command_in_pod`	Execute command in Pod
	`get_pod_linked_service`	Get Service linked to Pod
	`get_pod_linked_ingress`	Get Ingress linked to Pod
	`get_pod_linked_endpoints`	Get Endpoints linked to Pod
	`get_pod_linked_pvc`	Get PVC linked to Pod
	`get_pod_linked_pv`	Get PV linked to Pod
	`get_pod_linked_env`	Get runtime environment variables of Pod by running env command in Pod
	`get_pod_linked_env_from_yaml`	Get runtime environment variables of Pod from Pod yaml definition
	`get_pod_resource_usage`	Get resource usage of Pod, including CPU and memory request values, limit values, allocatable values, and usage ratios
YAML Management (2)	`apply_yaml`	Apply YAML resource
	`delete_yaml`	Delete YAML resource
Storage Management (3)	`set_default_storageclass`	Set default StorageClass
	`get_storageclass_pvc_count`	Get PVC count under StorageClass
	`get_storageclass_pv_count`	Get PV count under StorageClass
Ingress Management (1)	`set_default_ingressclass`	Set default IngressClass

v0.0.66 Update

Added MCP support
Built-in multi-cluster operations:
1. list_k8s_resource
2. get_k8s_resource
3. delete_k8s_resource
4. describe_k8s_resource
5. get_pod_logs

v0.0.67 Update

New MCP event query tool
New cluster registration query tool
Enhanced label-based resource filtering (e.g. app=k8m)
Added quick enable/disable toggle for MCP Server

Development & Debugging

If you want to develop and debug locally, please execute local frontend build once first to automatically generate the dist directory. Because this project uses binary embedding, the frontend will error without dist.

Step 1: Build Frontend

cd ui
pnpm run build

Compile and Debug Backend

# Download dependencies
go mod tidy
# Run
air
# Or
go run *.go 
# Listens on localhost:3618 port

Frontend Hot Reload

cd ui
pnpm run dev
# Vite service will listen on localhost:3000 port
# Vite forwards backend access to 3618 port

Visit http://localhost:3000

HELP & SUPPORT

If you have any further questions or need additional help, please feel free to contact me!

Special Thanks

zhaomingcheng01: Provided many high-quality suggestions, making outstanding contributions to k8m's usability and ease of use~

La0jin: Provided online resources and maintenance, greatly improving k8m's presentation

eryajf: Provided us with very useful github actions, adding automated release, build, publishing and other functions to k8m

Contact Me

WeChat (大罗马的太阳) Search ID: daluomadetaiyang, note k8m.