k8m Documentation

k8m is a lightweight, AI-driven Mini Kubernetes Dashboard designed for simplified cluster management. It is built using Golang (backend) and Baidu AMIS (frontend), and uses kom as its Kubernetes API client.

Key capabilities include:

• AI Integration: Provides intelligent support for resource explanation, YAML translation, log diagnosis, and command recommendations using built-in models (like Qwen2.5-Coder-7B) or custom models (via Ollama or private APIs).
• Multi-Cluster Management: Automatically recognizes clusters via InCluster mode or by scanning kubeconfig files in the same directory. Supports heartbeat detection and automatic reconnection.
• MCP Integration: Visual management of Model Context Protocol (MCP) tools, allowing large language models to execute Kubernetes operations via 49 built-in multi-cluster MCP tools.
• Plugin-Based Architecture: Features are modular and enabled on demand to minimize resource consumption.
• Pod Management: Supports real-time log viewing, file browsing (upload/download/edit/delete), and direct shell command execution within Pods.
• Security: Integrated multi-cluster permission management (Read-only, Exec, or Admin) and MCP permission integration, ensuring AI-driven operations respect user permissions.

Plugins transition through several explicit states. Understanding these states is critical for managing background tasks and data persistence:

Lifecycle Methods

• Install: Creates DB tables and initializes data. Must be idempotent. (Uninstalled $\rightarrow$ Installed)
• Upgrade: Performs DB migrations and version compatibility handling. Can be triggered in any state. (No state change)
• Enable: Registers routes and exposes menus/APIs. Does NOT start background tasks. (Installed/Disabled $\rightarrow$ Enabled)
• Disable: Hides menus and revokes routes. Automatically stops background tasks. (Enabled/Stopped $\rightarrow$ Disabled)
• Start: Starts non-blocking background goroutines or event listeners. (Enabled/Stopped $\rightarrow$ Running)
• Stop: Stops background goroutines and cleans up resources. (Running $\rightarrow$ Stopped)
• Uninstall: Removes plugin info and optionally deletes DB tables (based on keepData parameter). (Any state $\rightarrow$ Uninstalled)

The K8M frontend uses a custom fetcher (defined in ui/src/components/Amis/fetcher.ts) to wrap all HTTP requests. This fetcher is automatically injected into the AMIS rendering process.

Key Features

• Automatic Authentication: Automatically adds Authorization: Bearer ${token} from localStorage to every request.
• Cluster Context Injection: Automatically handles cluster URL rewriting. It supports specifying a target cluster via the x-k8m-target-cluster header or the __cluster query parameter.
• Error Handling:
  • 401: Automatically redirects to /#/login.
  • 512: Indicates insufficient cluster permissions; redirects to cluster user management.
  • 403: Indicates insufficient permissions.

Usage in AMIS Schema

When defining an AMIS component, the api field will automatically use this fetcher:

{
  "type": "crud",
  "api": {
    "method": "get",
    "url": "/k8s/cluster/${cluster}/pods"
  }
}

renderAmis(schema, initialData, {
    theme: 'cxd',
    fetcher,  // Injected custom fetcher
    isCancel: value => axios.isCancel(value),
})

K8M is built around a plugin architecture where all features are implemented as plugins with a full lifecycle. Plugins are discovered at compile time via Go registration.

Plugin Lifecycle

All lifecycle methods must be idempotent:

• Install(ctx): Create tables and initialize data.
• Upgrade(ctx): Migrate schema/data during version changes.
• Enable(ctx): Register routes and expose menus.
• Disable(ctx): Hide menus and unregister routes.
• Start(ctx): Start background goroutines or subscribe to the EventBus.
• Stop(ctx): Stop goroutines and clean up resources.
• StartCron(ctx, spec): Execute scheduled tasks.
• Uninstall(ctx): Delete tables (or retain data if requested).

Routing Types

Plugins use specific router types to define their scope:

• ClusterRouter: /k8s/cluster/{cluster}/plugins/{name}/* (Cluster-specific operations)
• ManagementRouter: /mgm/plugins/{name}/* (General management operations)
• PluginAdminRouter: /admin/plugins/{name}/* (Platform administrator operations)
• RootRouter: Root-level routes (rarely used)

Plugin Directory Structure

pkg/plugins/modules/{plugin-name}/
├── metadata.go          # Plugin metadata and capability declarations
├── lifecycle.go         # Lifecycle interface implementation
├── models/
│   ├── db.go           # Init/Upgrade/DropDB functions
│   └── *.go            # Model definitions
├── route/
│   ├── cluster_api.go  # Cluster operations
│   ├── mgm_api.go     # Management operations
│   └── admin_api.go   # Admin operations
├── frontend/
│   └── *.json          # AMIS JSON files
├── controller/          # HTTP handlers (optional)
└── service/             # Business logic (optional)