2026-04-24 #product#homelab#go#kubernetes

xcluster — control plane cho homelab

Tớ xây một platform để quản lý toàn bộ homelab từ browser — SSH terminal, Docker, Wake-on-LAN, monitoring. Viết bằng Go.

Homelab của tớ có vài con máy — chạy Docker, host services, thỉnh thoảng build Kubernetes cluster. Quản lý chúng nghĩa là mở terminal, SSH vào từng con, check CPU, restart container, rồi lặp lại cho con tiếp theo.

5 máy, 5 terminal sessions. Quên máy nào đang chạy gì. Máy nào đã tắt. Muốn wake thì phải nhớ MAC address.

Thế là tớ viết xcluster.

xcluster là gì

Một dashboard để control tất cả máy trong homelab từ browser. Không phải monitoring tool — mà là control plane thực sự: SSH vào máy, chạy command, quản lý Docker, wake/shutdown/reboot, tất cả từ 1 nơi.

Thứ tớ thích nhất khi build

Web terminal thật sự

Không phải cái textbox giả lập terminal. xcluster proxy WebSocket → SSH connection với full PTY allocation. Nghĩa là bạn mở terminal trên browser, nó hoạt động y như iTerm — tab completion, vim, htop, tmux, Ctrl+C, tất cả đều work.

Backend nhận WebSocket frame → pipe vào SSH session → pipe output ngược lại. Gorilla WebSocket handle connection, golang.org/x/crypto/ssh handle SSH protocol. Mỗi terminal session là một goroutine riêng, không block main thread.

Multi-auth SSH

Không phải mọi máy đều dùng cùng 1 cách auth. xcluster support:

  • Password — plain old password, encrypted at rest bằng AES-256-GCM
  • PEM file — upload private key, store encrypted
  • Default SSH key — dùng ~/.ssh/id_rsa của server
  • xcluster key — auto-generate ED25519 keypair, tự provision vào target machine

Tất cả credentials encrypt trước khi store. Key derivation từ server secret. Không bao giờ lưu plaintext.

Smart cluster operations

Khi reboot cluster, thứ tự quan trọng. Reboot master trước workers = downtime. xcluster hiểu topology — workers shutdown trước, master cuối cùng. Wake thì ngược lại — master first.

Bulk operations với concurrency control — không spam tất cả máy cùng lúc.

Real-time metrics không cần agent

Không cần install agent trên target machines. xcluster SSH vào, chạy cat /proc/stat, free -b, df -B1, parse output, store metrics. Background cron job mỗi 30 phút. Pusher broadcast metrics tới tất cả connected dashboard clients — update live mà không cần refresh.

Đúng, nó SSH vào mỗi máy mỗi 30 phút để lấy metrics. Không elegant bằng Prometheus + node_exporter, nhưng zero setup trên target machines. Plug and play.

Docker management qua SSH

xcluster không cần Docker socket access trên remote machines. Nó SSH vào, chạy docker ps, docker inspect, parse JSON output. Manage containers, images, volumes, networks — tất cả qua SSH tunnel.

Nghĩa là bạn có thể quản lý Docker trên máy remote mà không cần expose Docker API ra network. Security by default.

Architecture

Go backend — chọn Go vì: goroutines cho concurrent SSH sessions, compiled binary nhỏ (Alpine image ~20MB), strong typing, excellent SSH libraries.

Structure theo DDD: domain/machine, domain/cluster, domain/metric, domain/docker, domain/terminal. Mỗi domain có handler → service → repository. Dependency Injection container wire tất cả lại.

React frontend — Vite + React 19 + TypeScript. Terminal UI dùng xterm.js — same library mà VS Code dùng cho integrated terminal. Monaco Editor cho config editing (YAML, JSON).

Type-safe SDK — OpenAPI spec auto-generate từ Go code (swag annotations). CI pipeline convert sang TypeScript types → publish SDK package. Frontend import SDK → type-safe API calls. Thay đổi API trên backend → types tự update trên frontend. Zero manual sync.

Roadmap

Đang phát triển mở rộng cho Kubernetes:

  • Kubernetes cluster provisioning (kubeadm, k3s)
  • Pod/Deployment/Service management từ dashboard
  • Helm chart deployment
  • Log streaming từ pods
  • Resource metrics dashboard (CPU, memory per pod/node)
  • kubectl proxy qua web terminal

Private

xcluster hiện tại là private project. Nếu quan tâm, liên hệ để trao đổi thêm.