Bỏ qua

ADR-0001: Stateful services chạy Docker Compose trên master node, không phải K8s StatefulSet

  • Status: Accepted
  • Date: ~2026-06-27 (backfilled 2026-07-25)
  • Supersedes: —
  • Superseded by: —

Bối cảnh

Cụm K3s 3 node (1 master + 2 worker) cần chạy PostgreSQL, MongoDB, Redis, Kafka+Zookeeper, Keycloak, và OmniRoute LLM router. Các service này giữ state quan trọng (dữ liệu booking, session). Có 2 hướng: chạy trong K3s bằng StatefulSet + PersistentVolume, hoặc chạy ngoài K3s bằng Docker Compose trên riêng master node.

Quyết định

Chạy toàn bộ stateful stack qua Docker Compose trên master node, tách biệt khỏi K3s workload. K3s worker chỉ chạy stateless app (NestJS, chatbot) deploy qua Helm, kết nối ngược vào stateful stack trên master qua network.

Lựa chọn khác đã cân nhắc

  • StatefulSet + PV trong K3s: đồng nhất công cụ quản lý (chỉ Helm/kubectl, không cần Ansible role riêng cho Docker Compose), nhưng phức tạp hơn nhiều ở quy mô 3-node cluster tự vận hành (local-path provisioner không có replication, backup/restore PV thủ công hơn, StorageClass cần tự cấu hình) — loại vì overhead vận hành không tương xứng lợi ích ở quy mô hiện tại.
  • Managed DB service (RDS-tương-đương): giảm effort vận hành nhưng phát sinh chi phí và phá vỡ mục tiêu tự chủ hạ tầng trên Oracle Cloud free tier
  • UTM local — loại.

Hệ quả

  • Được: vận hành/backup/restore Postgres-Mongo-Redis-Kafka đơn giản hơn bằng docker compose quen thuộc; tách biệt rõ ràng giữa "hạ tầng dữ liệu" (Ansible + Compose) và "ứng dụng" (Helm + K3s).
  • Đánh đổi: master node là single point of failure cho toàn bộ dữ liệu — không có tự động failover; scale theo chiều ngang cho DB phải làm thủ công (không tận dụng được K8s scheduling); mọi worker phụ thuộc network reachability tới master.

Liên kết

  • Docs liên quan: README.md (mục Kiến trúc tổng quan), roles/stateful_stack/