English | 简体中文

AliangBoard

Open-source, AI-native Kubernetes management panel — natural-language operations on top of full multi-cluster management.

AliangBoard turns an LLM into an operator for your clusters: with the built-in Agent workbench and MCP server, you can ask in natural language to read pod logs, debug containers, roll back a release, or modify resources. At the same time it is a complete Kubernetes panel covering the full resource lifecycle, exec / port-forward / debug-container injection, and multi-cluster switching.

Tech stack in one line: a Vue 3 + Vite + Pinia frontend (plain JS, no TypeScript) and a Node transparent Kubernetes API gateway (zero extra runtime dependencies).

🌐 Live Demo

Item	Value
Demo site	🚀 Open the live demo
Username	admin
Password	admin123

The demo is a public, shared instance: anything you create or change is visible to other visitors, so please do not put anything sensitive on it.

📸 Screenshots

Namespace Overview — layered topology of a namespace (monitoring / business / database / storage layers) with health at a glance:

Workload Overview — a single workload at a glance: replicas, ready pods, image, events, CPU / memory and containers:

✨ Features

🤖 AI Operations

• Agent workbench + MCP server (Streamable HTTP, API-key auth)
• Tiered tools: read (free) / operator / admin (human-approved); writes are always human-approved
• Full audit log (who / verb / resource / HTTP code)
• Park a chat in the background and reopen it anytime from the floating entry point

🔌 Cluster & Multi-Cluster

• Bearer Token / Basic Auth connection validation, session restore, logout
• Connected clusters are persisted; one-click switch or remove

🗂 Full Resource Lifecycle

• 30+ resource types synced; structured creation forms (20 built-in kinds) persisted via Server-Side Apply
• YAML editing / export; optimistic delete with rollback on failure; apply multi-document YAML in one shot
• Resource coverage table (see below)

Category	Resources
Core Workloads	Pod · Deployment · StatefulSet · DaemonSet
Networking	Service · Ingress · Endpoints · NetworkPolicy · IngressClass
Config & Storage	ConfigMap · Secret · PVC · PV · StorageClass
RBAC	Role · ClusterRole · RoleBinding · ClusterRoleBinding · ServiceAccount
Cluster & Policy	Namespace · Node · Event · RuntimeClass · PriorityClass · ResourceQuota · LimitRange · PDB
Autoscaling	HPA
Extensions	CRD + custom resources (API-discovery driven)

🖥 Pod Deep Operations

• exec terminal (xterm.js, tmux-backed: survives a page refresh)
• attach · port-forward (Service / Deployment resolved to backend pods via endpoints)
• File browsing (upload / download with progress) · kubectl debug injection (ephemeral containers)

🔁 Rollout & Node Ops

• scale · rolling restart · rollout undo · CronJob manual trigger
• Node cordon / uncordon / drain (policy/v1 Eviction)

🔍 Navigation & Insights

• Global search across resources and namespaces · ownerReferences ownership topology with clickable jumps
• Events live watch + involvedObject filtering
• Namespace application layers (presentation / gateway / microservices / middleware / persistence, heuristic by default, exact via label layer.aliangboard.io)
• Metrics charts (CPU / memory sampling, 15-min persisted window)

🚀 Quick Start

Kubernetes (recommended)

One command installs into the aliangboard namespace (NodePort exposure, 1Gi PVC dynamically provisioned by the default StorageClass):

kubectl apply -f https://raw.githubusercontent.com/aliang-one/aliangboard/main/deployment.yaml
kubectl -n aliangboard get svc aliangboard   # read the NodePort from the PORT(S) column, e.g. 8787:31234/TCP

Open http://<any-node-IP>:<NodePort> in your browser.

• Default administrator admin / admin — seeded via ADMIN_USERNAME / ADMIN_PASSWORD on first start only (changing the env after seeding has no effect); set strong credentials before applying in production
• Panel data (API keys, cluster credentials, audit log, workbench repository) persists in the aliangboard-data PVC; the SQLite store is single-replica — do not scale replicas
• When running inside a Kubernetes cluster, use https://kubernetes.default.svc as the API address, but the default ServiceAccount has no RBAC (you will get 403): create your own ServiceAccount with the required RBAC, obtain a token with kubectl create token, and supply the cluster CA certificate (or skip verification with the insecure option, development only)
• Uninstalling removes all data: kubectl delete ns aliangboard (namespace deletion cascades to the PVC)

Docker

Images are published on GHCR:

docker pull ghcr.io/aliang-one/aliangboard:latest
docker run -d --name aliangboard \
  -p 8787:8787 \
  -v aliangboard-data:/app/data \
  ghcr.io/aliang-one/aliangboard:latest

Or build locally:

docker build -t aliangboard .
docker run -d --name aliangboard -p 8787:8787 -v aliangboard-data:/app/data aliangboard

Open http://localhost:8787 in your browser. The SQLite database and the workbench git repository persist in the aliangboard-data volume — it contains credentials, keep it safe.

From source

Requires Node.js 25+ (the server uses the built-in node:sqlite module, which is flag-free from Node 25; on 22–24 it is experimental and needs --experimental-sqlite). You also need network access to the target Kubernetes API server and a token or account with the required RBAC permissions.

git clone https://github.com/aliang-one/aliangboard.git aliangboard && cd aliangboard
npm install
npm run server   # terminal 1: API gateway
npm run dev      # terminal 2: frontend dev server (Vite proxies /api → 127.0.0.1:8787)

Production build: npm run build (output in dist/, served same-origin by the gateway's server/static.mjs).

🤖 AI Workbench & MCP

AliangBoard turns an LLM into a cluster operator via two paths.

Built-in Agent Workbench

Chat with your cluster directly in the admin console ("Agent Console"). The agent calls a set of Kubernetes tools through a bound ServiceAccount:

• Read (no approval): pod logs · list / get resources and YAML · events · can-i RBAC self-check · rollout history
• Operator (human approval): scale (1..20, no scaling to 0) · rolling restart
• Admin (human approval): exec commands · read / browse container files · apply / delete resources · update image · kubectl debug injection · rollback to a specific revision

Every write goes through a human-approval checkpoint — the agent proposes, you confirm, nothing changes your cluster silently.

MCP Server (external AI clients)

AliangBoard is also an MCP server (POST /mcp, Streamable HTTP, API-key auth) that exposes the same toolset to external AI clients such as Claude Code:

claude mcp add --transport http aliangboard {HOST}/mcp \
  --header "Authorization: Bearer <YOUR_API_KEY>"

Remove it with: claude mcp remove aliangboard

Bring Your Own LLM

The agent speaks the OpenAI-compatible protocol. Set baseURL + apiKey + model in the admin console ("LLM Settings"), or set the environment variables LLM_BASE_URL / LLM_MODEL. OpenAI, DeepSeek, Qwen, GLM, and local vLLM / Ollama (with an OpenAI-compatible endpoint) all work.

Security Model

• Every API key is bound to one ServiceAccount; tool calls are constrained by that SA's Kubernetes RBAC
• Tools are tiered read / operator / admin; minTier filters the tools available to each key
• Writes and workbench file writes always require human approval
• Every call is recorded in the audit log (who / verb / resource / HTTP code)

⚙️ Configuration

Backend environment variables:

Variable	Default	Description
HOST	127.0.0.1	API gateway listen address
PORT	8787	API gateway listen port
CORS_ORIGIN	*	Allowed frontend origins; set to your actual domain in production
SESSION_TTL_MS	28800000	In-memory session lifetime, 8 hours by default
MAX_PLATFORM_SESSIONS_PER_USER	10	Max platform sessions kept per user; the least recently active one is evicted on login when exceeded, disabled when < 1
K8S_REQUEST_TIMEOUT	15000	Kubernetes API request timeout, in milliseconds
K8S_ALLOWED_HOSTS	empty	Comma-separated allowlist of API server hosts
K8S_INSECURE_SKIP_TLS_VERIFY	false	Skip cluster certificate verification for K8s sessions only; does not disable process-level TLS (LLM/version checks unaffected). Use only in development with self-signed clusters
PORT_FORWARD_HOST	127.0.0.1	Port-forward local listen address (same as kubectl port-forward; local to the gateway host, the browser must be able to reach it)
LLM_BASE_URL	empty	OpenAI-compatible baseURL for the LLM (can also be set in the admin console "LLM Settings")
LLM_MODEL	empty	LLM model name (can also be set in the admin console)

Frontend environment variables:

Variable	Default	Description
VITE_API_BASE_URL	empty	Full address of the API gateway; keep empty for same-origin deployments
ALIANGBOARD_API_URL	http://127.0.0.1:8787	Vite dev proxy target

To connect to a cluster with a self-signed certificate during development, you can temporarily run:

K8S_INSECURE_SKIP_TLS_VERIFY=true npm run server

Note: This variable only affects K8s session verification (TLS to the cluster API server). It does not disable process-level TLS verification for LLM calls or version checks. Use only in development/self-signed environments.

🔒 Production Deployment Security Requirements

TLS Termination

Production deployments MUST terminate TLS at an edge layer (reverse proxy or Ingress Controller). The default NodePort exposure in deployment.yaml is intended for internal network evaluation only.

• Ingress (recommended): See deploy/ingress-tls.yaml for a complete nginx Ingress + TLS example
  • TLS is terminated at the Ingress layer
  • Backend Service remains plain HTTP (containerPort: 8787)
  • Supports cert-manager automation or manual TLS secrets
• Alternative reverse proxy: Configure nginx/HAProxy/Envoy with TLS termination, proxying to the NodePort or Service

K8s Session TLS

The K8S_INSECURE_SKIP_TLS_VERIFY environment variable has session-scoped semantics:

• Purpose: Only controls TLS verification for K8s cluster connections (session-level)
• Does NOT affect: Process-level TLS (LLM API calls, version checks, etc.)
• Use case: Development/self-signed clusters only
• Production: Configure a trusted CA and K8S_ALLOWED_HOSTS instead

Do not skip TLS verification in production without proper security review.

🔐 RBAC Recommendations

Do not use long-lived cluster-admin tokens. Create a dedicated ServiceAccount and grant only what your usage actually needs:

• get, list, watch on resources
• create, update, patch, delete on the resources you need to edit
• get on pod logs
• create on pod eviction
• patch for node operations
• pods/exec (create) for the exec terminal
• pods/portforward (get / create) for port forwarding
• pods/ephemeralcontainers (update) for debug container injection
• pods/attach (create) for pod attach
• jobs (create) for CronJob manual trigger

The API gateway keeps cluster credentials and sessions in memory by default, so all login sessions are lost on restart (with container deployment, credentials persist in the /app/data volume). For multi-instance production deployments, move sessions and encrypted cluster credentials to dedicated storage.

🐳 Container Deployment & Release

The repository ships a multi-stage Dockerfile: a single Node process serves both the frontend static files and the API gateway, ready to run out of the box.

Container variables (they override the backend variables of the same name):

Variable	Default	Description
HOST	0.0.0.0	Listen address inside the container (set by the image; do not change it back to 127.0.0.1)
PORT	8787	Listen port
ALIANG_DB	/app/data/aliangboard.db	SQLite database path (inside the volume)
ALIANG_WORKBENCH_DIR	/app/data/workbench	Workbench git repository directory (inside the volume)
ALIANG_STATIC_DIR	/app/dist	Frontend static directory (rarely needs changing)

The runtime image is based on node:25-alpine (hard requirement for node:sqlite) with git built in (needed for the workbench repository). It runs as the non-root user node.

Release & CI

• Builds are triggered only by pushing a v* tag (e.g. v1.2.3) or by a manual workflow_dispatch from the Actions page. Regular pushes do not build images.
• Published image tags on GHCR:
  • ghcr.io/aliang-one/aliangboard:latest — follows the newest release
  • ghcr.io/aliang-one/aliangboard:1.2.3 — immutable semver pin, for exact version lock
  • ghcr.io/aliang-one/aliangboard:1.2 — rolls with each minor release
• Multi-platform linux/amd64 + linux/arm64; authentication uses the built-in GITHUB_TOKEN, no extra secrets required
• Historical images can be pruned via the manual cleanup workflow (.github/workflows/cleanup-ghcr.yml, dry-run by default)
• Current release: v1.0.3

🖥 SSH Server Management

Manage SSH servers alongside Kubernetes clusters — credentials stored AES-256-GCM encrypted (key file kept separate from the database).

• Server inventory: host/port/credentials (password or private key + sudo password), optional cluster association and tags; connection test detects the distro (Ubuntu/Debian/Arch/Alpine/Rocky…) and shows its icon plus a health badge.
• Workbench terminals: interactive floating terminals with gateway-side keepalive — refreshing the page replays scrollback and resumes the same shell.
• SFTP: browse/upload/download with progress.
• AI access (opt-in per server): each server has an "expose to AI" toggle with an approval policy (always = every command human-approved, readonly = read-only commands auto-allowed, none = unrestricted). Exposed servers appear in the AI ledger (read_server_ledger) where the agent records each server's role/deployments (write_server_notes, human-approved).

Authorization model (deliberately simple, open-source edition):

• Server CRUD, credentials and the ledger are admin-only; terminals, SFTP and AI access are admin-only as well.
• API keys can be granted SSH access with a single boolean (SSH server access when creating/editing a key). Granted keys reach MCP tools wb_ssh_exec / wb_ssh_read_file / read_server_ledger for servers that are exposed to AI; each server's approval policy applies in a fail-closed way (always denies exec on the key channel since no human approver exists there). No grouping or per-user permission management.

⚠️ Known Limitations

• The exec terminal, port forwarding, and file browsing only work when a real cluster is connected; without one, the related entry points show an empty state.
• Port forwarding opens a local TCP listener on the gateway host (default 127.0.0.1, same as kubectl port-forward). When the panel runs on a remote host, the browser cannot reach that port directly — use an SSH tunnel or similar.
• The exec terminal runs /bin/sh by default (adjustable via the component's command prop); for shell-less images such as distroless, use kubectl debug to inject an ephemeral container with a shell (requires Kubernetes 1.25+; EphemeralContainers is enabled by default).
• Multi-cluster switching reuses the gateway session; sessions are lost when the gateway restarts, so saved clusters must be logged into again. Session credentials live only in the browser's localStorage — do not use them on shared devices.
• The "Audit" page shows cluster Events as the activity record; full user-level auditing (who / verb / IP / HTTP code) requires cluster audit logging wired to a log backend — the standard Kubernetes API does not provide it.
• Helm, GitOps, and alerting are not integrated yet.
• HPA / PDB depend on specific API versions (e.g. autoscaling/v2, policy/v1); on older clusters the corresponding creation fails with a toast message.
• When deployed inside a Kubernetes cluster, the port-forward listener opens in the panel Pod's network namespace and the browser cannot reach it directly; this capability targets Docker / source deployments and is unavailable for in-cluster installs (a gateway-side proxy may come later).

🛠 Tech Stack

Frontend — Vue 3 · Vite · Pinia · Vue Router · @tanstack/vue-query · vue-i18n · xterm.js · marked · DOMPurify (plain JS, no TypeScript)

Backend — Node.js 25 (built-in node:sqlite) · @kubernetes/client-node · transparent Kubernetes API gateway with zero extra runtime dependencies

Testing — server and pure-logic tests on an in-house zero-dependency runner + node --test; frontend unit tests with vitest + @vue/test-utils + happy-dom

Packaging — a single multi-stage Docker image (node:25-alpine), one process serving API + SPA same-origin

🤝 Contributing

Issues and PRs are welcome. Local development:

npm install
npm run server     # API gateway
npm run dev        # frontend
npm test           # server + pure-logic tests
npm run test:unit  # frontend unit tests (vitest)
npm run typecheck  # node --check syntax baseline

Bilingual sync rule: any change to README.md must update README.zh-CN.md in the same PR.

License

Apache License 2.0. Commercial use, modification, distribution, and private use are permitted, provided the copyright and license notices are retained.