HA-Master: Hệ thống quản lý HAProxy Master–Agent | Blog

Open-Source · Go + React · Phase 6 Complete

HA-Master

Hệ thống quản lý HAProxy tập trung theo mô hình Master–Agent. Deploy config tới hàng trăm node, không cần SSH, có audit trail đầy đủ.

Go 1.22 React 18 PostgreSQL 16 gRPC + mTLS Docker ✓ 6 Phases Complete

Xem Demo UI Kiến trúc hệ thống

100+

Nodes / Cluster

DB Tables

<5s

Deploy / Node

mTLS

Agent Security

AES-256

Key Encryption

VẤN ĐỀ / THE PROBLEM

Quản lý HAProxy thủ công rất khó scale

Khi số lượng node tăng lên, mô hình SSH-to-each-server bộc lộ nhiều điểm yếu nghiêm trọng.

⚠️

SSH từng máy — không scalable

Mỗi lần thay đổi config phải SSH vào từng node, copy file thủ công. Với 50+ node, quá trình này tốn hàng giờ và dễ xảy ra sai lệch giữa các máy.

🔍

Không có audit trail

Không biết ai đã thay đổi gì, khi nào. Khi incident xảy ra, việc truy vết nguyên nhân gần như không thể nếu không có log đầy đủ.

🔄

Rollback thủ công = downtime

Config lỗi trên production? Phải SSH từng máy để restore file cũ. Không có snapshot, không có history, không có automated rollback.

🔐

Bảo mật kém với SSH keys

Mỗi engineer cần SSH key tới tất cả nodes. Quản lý key rotation phức tạp. Risk surface lớn khi key bị lộ.

📊

Không có visibility

Không biết node nào đang chạy config version nào. Trạng thái deployment (success/failed/pending) hoàn toàn mù quáng.

🧩

Config drift giữa các node

Node A và Node B có thể đang chạy 2 version config khác nhau mà không ai hay biết — dẫn đến behavior không nhất quán.

GIẢI PHÁP / SOLUTION

HA-Master — Single Pane of Glass

Quản lý toàn bộ HAProxy cluster từ một giao diện duy nhất. Không SSH, không manual, fully audited.

🗄️

Database là Source of Truth

Config không nằm trên node mà nằm trong PostgreSQL. Mỗi thay đổi tạo ra một immutable config version với SHA-256 hash. Node chỉ là nơi apply config.

🔗

Agent-Initiated gRPC (Firewall-Safe)

Agent chạy trên node chủ động kết nối tới Master qua gRPC bidirectional stream. Không cần mở inbound port trên node — an toàn với firewall enterprise.

♻️

Idempotent Deployment

Mỗi deployment so sánh SHA-256 hash. Nếu node đã có đúng config version → skip. Retry bao nhiêu lần cũng an toàn, không có side effect.

🛡️

mTLS + AES-256-GCM Security

Tất cả giao tiếp giữa Agent và Master đều qua mTLS. Private keys của SSL certificate được mã hóa AES-256-GCM trước khi lưu vào DB.

📋

Full Audit Trail

Mọi action đều được log với user attribution, timestamp, và correlation ID. Biết chính xác ai deploy gì, khi nào, kết quả ra sao.

// Core principle

config_versions

↓ SHA-256 hash

↓ immutable snapshot

↓ never modified

deployments

↓ batch/rolling

↓ advisory lock

↓ retry × 3

agents (per node)

↓ haproxy -c (validate)

↓ atomic write

↓ haproxy reload ✓

// Idempotency check

node.config_hash ==

target.config_hash:

skip // safe noop

KIẾN TRÚC / ARCHITECTURE

Master–Agent Model

3 tầng rõ ràng: Frontend → Master → Agents. Không SSH, không direct access vào node.

⚛️

React Frontend

Vite · TypeScript · TanStack Query

←→

REST API
:8080

⚙️

Master Service

Go 1.22 · Echo · gRPC Server

←→

SQL
ACID

🗄️

PostgreSQL 16

8 tables · Source of Truth

gRPC :50051 · mTLS · Agent-Initiated

🤖

Agent 1

node: web-01

🤖

Agent 2

node: web-02

🤖

Agent N

100+ nodes

⚖️

HAProxy

web-01 · socket cmd

⚖️

HAProxy

web-02 · socket cmd

Master Service

React Frontend

Go Agent

PostgreSQL

HAProxy Process

Agent → Master (outbound only, mTLS)

Database Schema — 8 Tables

● users — auth, RBAC roles

● clusters — node grouping

● nodes — HAProxy servers

● config_versions — immutable snapshots

● deployments — deploy tracking

● deployment_targets — per-node status

● refresh_tokens — JWT rotation

● certs — SSL, AES-256 encrypted

CÔNG NGHỆ / TECH STACK

Battle-tested, minimal dependencies

Chọn lọc kỹ — mỗi thư viện đều có lý do rõ ràng. Không over-engineer.

🐹

Go 1.22

Master + Agent backend

⚛️

React 18

TypeScript, Vite HMR

📡

gRPC

Protobuf, bidi stream

🐘

PostgreSQL 16

ACID, advisory locks

🌊

Tailwind CSS v4

Utility-first styling

🐻

Zustand

Auth state management

🔄

TanStack Query

2s polling, caching

📝

Monaco Editor

HAProxy syntax highlight

🔑

JWT + RBAC

15min/7d tokens, 3 roles

🔐

mTLS

Internal CA, CN=node_id

🔒

AES-256-GCM

Keys at rest encryption

🐳

Docker Compose

Dev environment

TÍNH NĂNG / FEATURES

Đầy đủ tính năng cho production

Từ quản lý config đến SSL cert management — tất cả trong một hệ thống.

🖥️

Node & Cluster Management

Đăng ký node qua API, nhận cert bundle tự động. Nhóm node vào cluster logic để deploy đồng thời. Heartbeat real-time cho phép phát hiện node offline trong <30s.

Heartbeat Auto cert 100+ nodes

📝

Config Editor & Versioning

Monaco editor với syntax highlighting cho HAProxy config. Mỗi lần save tạo immutable version mới với SHA-256 hash. Diff viewer so sánh giữa các version.

Monaco Immutable Diff viewer

🚀

Deployment Engine

Rolling deploy với batch_size tùy chỉnh. Advisory lock ngăn duplicate execution. Retry tối đa 3 lần với exponential backoff. Hỗ trợ stop-on-failure hoặc continue.

Rolling Rollback Idempotent

⚡

Runtime Control

Enable/disable backend servers không cần reload HAProxy. Điều chỉnh weight để shift traffic gradually. Show stats real-time từ HAProxy stats socket.

No reload Socket cmd Whitelisted

🔐

SSL Certificate Management

Upload cert và private key qua UI. Key được mã hóa AES-256-GCM trước khi vào DB. Push cert tới các node, agent ghi vào /etc/haproxy/ssl/ và reload HAProxy.

AES-256-GCM Expiry badge Push to node

👥

Auth & RBAC

JWT authentication với access token 15min + refresh token 7 ngày. 3 roles: viewer (read-only), operator (deploy + runtime), admin (full access). Mọi action đều được audit log.

JWT 3 Roles Audit log

GIAO DIỆN / UI DEMO

Trực quan, dễ dùng cho ops team

4 màn hình chính của HA-Master — từ dashboard tổng quan đến quản lý SSL certificate.

https://ha-master.internal/dashboard

Total Nodes

Clusters

Deploys Today

98.5%

Success Rate

Node Status

Node	Status	Cluster	Config	Last Seen
web-01.prod	online	production	a3f8c1d…	2s ago
web-02.prod	online	production	a3f8c1d…	3s ago
web-03.prod	degraded	production	b7d2a4e…	45s ago
lb-01.stg	offline	staging	—	2m ago
lb-02.stg	online	staging	c9f1b3a…	8s ago

https://ha-master.internal/configs/a3f8c1d7

Versions

📄 v8 (current)

📄 v7

📄 v6

📄 v5

📄 v4

haproxy.cfg

+ New version

# HAProxy Configuration v8
 
global
    maxconn 50000
    log 127.0.0.1 local0
    user haproxy
 
defaults
    mode http
    timeout connect 5s
    timeout client 30s
    timeout server 30s
 
frontend web_front
    bind *:80
    default_backend web_servers
 
backend web_servers
    balance roundrobin
    server app1 10.0.1.1:8080 check
    server app2 10.0.1.2:8080 check

https://ha-master.internal/deployments/new

✓

Cluster

Config

Options

Confirm

Select Config Version

a3f8c1d7 — latest

Saved 2026-05-05 14:32 by admin

✓

b7d2a4e2

Saved 2026-05-04 09:15 by operator

c9f1b3a8

Saved 2026-05-02 17:48 by admin

DEPLOYMENT SUMMARY

Cluster: production Nodes: 3 Batch size: 1 Strategy: rolling

https://ha-master.internal/certs

SSL Certificates

📎 Drag & drop .pem / .crt / .key files, hoặc click để chọn file

Domain	Issuer	Expires	Status	Actions
*.example.com	Let’s Encrypt	2026-08-12	99 days	Push · Delete
api.example.com	DigiCert	2026-06-02	28 days	Push · Delete
admin.internal.com	Internal CA	2026-05-10	5 days	Push · Delete
*.api.example.com	Let’s Encrypt	2026-12-20	229 days	Push · Delete

⚠️ admin.internal.com sẽ hết hạn trong 5 ngày. Hãy renew và push lên các node.

QUICK START

Chạy trong 5 phút với Docker

Môi trường development đầy đủ với 1 lệnh Docker Compose.

            Docker Compose (Recommended)
            bash
          
# Clone repository
git clone https://github.com/your-org/ha-master
cd ha-master

# Copy env file và chỉnh sửa
cp .env.example .env

# Start toàn bộ stack
# (Master + 2 Agents + PostgreSQL)
docker-compose up -d

# Tạo admin user (chỉ lần đầu)
docker-compose exec master \
  ./master –seed

# Mở browser
open http://localhost:3000

            Manual (Dev Mode)
            bash
          
# Prerequisites
# Go 1.22+ | Node 18+ | PostgreSQL 16

# Start Master
go run ./cmd/master
# → HTTP :8080 | gRPC :50051

# Start Agent (trên mỗi node)
NODE_ID=web-01 \
  MASTER_ADDR=localhost:50051 \
  go run ./cmd/agent

# Start Frontend
cd frontend
npm install && npm run dev
# → http://localhost:3000

          Environment Variables
          .env
        
# Master
DATABASE_URL=postgres://…
JWT_SECRET=your-secret
INTERNAL_CA_CERT=/path/ca.crt
INTERNAL_CA_KEY=/path/ca.key
CERT_ENCRYPTION_KEY=32-byte-key
# Agent
NODE_ID=web-01
MASTER_ADDR=master:50051
AGENT_CERT=/path/agent.crt
AGENT_KEY=/path/agent.key
HAPROXY_SSL_DIR=/etc/haproxy/ssl

ROADMAP

Từ scaffolding đến production-ready

6 phase hoàn thành. Phase 7+ đang trong kế hoạch.

✓

Phase 1

Scaffolding & Infrastructure

Go module Proto schema DB migrations Docker setup React+Vite scaffold

✓

Phase 2

Agent Core — gRPC, Heartbeat, Deploy, Runtime

gRPC bidi stream mTLS certs Heartbeat loop Config apply Socket runtime

✓

Phase 3

Master API — REST, gRPC Server, JWT Auth, CA Issuer

Echo router JWT 15min/7d RBAC 3 roles Internal CA Node registration

✓

Phase 4

Deployment Engine — Batch, Retry, Rollback, Advisory Lock

Polling loop Advisory lock Retry × 3 Rolling deploy Rollback API

✓

Phase 5

Frontend — All Pages, TanStack Query, Auth Flow

Dashboard Config editor Deploy wizard 2s polling 401 auto-refresh

✓

Phase 6

SSL Certificate Store — AES-256-GCM, Push to Nodes

Cert upload AES-256-GCM Expiry badges InstallCert handler Smoke test

Phase 7 — Planned

Testing, Metrics & Observability

Unit tests 80% Integration tests Prometheus metrics Structured logging Perf tuning

Phase 8 — Future

HA Master, ACME/Let’s Encrypt, Grafana

Multi-master HA ACME auto-renew Grafana dashboards PagerDuty alerts Config templates

KẾT LUẬN

Quản lý HAProxy không cần SSH nữa

HA-Master giải quyết tất cả pain point của việc quản lý HAProxy thủ công: từ config versioning, idempotent deployment, đến SSL cert management — tất cả qua một giao diện web duy nhất, có audit trail đầy đủ và bảo mật với mTLS + AES-256.

Dự án đang trong giai đoạn tích cực phát triển. Phase 7 (testing + metrics) sắp bắt đầu.

Xem kiến trúc Demo UI

Go 1.22· React 18 + TypeScript· PostgreSQL 16· gRPC + Protobuf· mTLS· AES-256-GCM· Docker Compose

Vibe Code dự án đầu tiên