football-booking-infra-k3s

Infrastructure-as-Code cho hệ thống Football Booking — tự động hóa toàn bộ quá trình provision và deploy lên cụm K3s 3 node bằng Ansible + Helm.

📋 Xem SERVICES.md để biết danh mục đầy đủ tất cả repo trong hệ thống (mục đích, tech stack, docs, CI/CD).

Kiến trúc tổng quan

┌─────────────────────────────────────────────────────┐
│                   MASTER NODE                       │
│                                                     │
│  Docker Compose — stateful services                 │
│  ├── PostgreSQL 16   (port 5432)                    │
│  ├── MongoDB 7       (port 27017)                   │
│  ├── Redis           (port 6379)                    │
│  ├── Kafka + Zookeeper (port 9092/9093)             │
│  ├── Keycloak        (port 8080)                    │
│  └── OmniRoute LLM  (port 20128)                   │
│                                                     │
│  Docker Compose — observability                     │
│  ├── ClickHouse + SigNoz (metrics/traces/logs)      │
│  ├── OpenTelemetry Collector                        │
│  ├── LangFuse (LLM observability)                   │
│  └── MinIO (blob storage cho LangFuse)              │
│                                                     │
├─────────────────────────────────────────────────────┤
│              WORKER NODE 1 & 2                      │
│                                                     │
│  K3s Workloads — Helm charts                        │
│  ├── api-gateway       (NestJS)                     │
│  ├── user-service      (NestJS)                     │
│  ├── field-service     (NestJS)                     │
│  ├── booking-service   (NestJS)                     │
│  ├── payment-service   (NestJS)                     │
│  ├── notification-service (NestJS)                  │
│  ├── chatbot-service   (Python/FastAPI)             │
│  └── nginx-ingress     (load balancer)              │
└─────────────────────────────────────────────────────┘

Luồng request: Client → nginx-ingress → api-gateway → microservices → stateful services

Tech Stack

Layer	Tool	Vai trò
Orchestration	K3s v1.29.4	Lightweight Kubernetes, 3 node (1 master + 2 worker)
Provisioning	Ansible	Cài đặt OS, K3s, Docker, deploy toàn bộ services
Secret management	Ansible Vault	Encrypt secrets trước khi commit
App deploy	Helm 3	Deploy stateless NestJS/chatbot workloads lên K3s
Stateful services	Docker Compose	PostgreSQL, MongoDB, Redis, Kafka, Keycloak trên master
CI/CD	GitHub Actions	Reusable workflows, deploy qua SSH + `helm upgrade --atomic`
Networking	nginx-ingress	Route traffic từ ingress vào api-gateway
CNI	Flannel VXLAN	Pod networking giữa các nodes
Observability	SigNoz + LangFuse	APM traces/metrics + LLM call tracking
LLM routing	OmniRoute	Multi-provider router (Groq / Gemini / Anthropic)

Cấu trúc thư mục

football-booking-infra-k3s/
├── ansible.cfg                    # Cấu hình mặc định Ansible (inventory, SSH key)
├── secrets/
│   └── vault.yml                  # ⚠ Secrets (PHẢI encrypt trước khi commit)
├── inventory/
│   ├── utm/                       # Môi trường local (UTM VM, 192.168.64.x)
│   │   ├── hosts.ini
│   │   └── group_vars/
│   └── oracle/                    # Môi trường Oracle Cloud (IP thật)
│       ├── hosts.ini
│       └── group_vars/
├── playbooks/
│   ├── site.yml                   # Full provision từ đầu (chạy 1 lần)
│   ├── deploy.yml                 # Re-deploy tất cả apps
│   └── deploy_service.yml         # Deploy thủ công 1 service cụ thể
├── roles/
│   ├── common/                    # OS baseline: swap, sysctl, UFW, packages
│   ├── docker/                    # Cài Docker Engine + Compose plugin
│   ├── k3s_master/                # Cài K3s server, lấy node-token
│   ├── k3s_worker/                # Join cluster bằng token từ master
│   ├── kubeconfig/                # Fetch kubeconfig về máy local
│   ├── stateful_stack/            # Deploy Docker Compose stacks lên master
│   ├── helm_apps/                 # Deploy Helm charts lên K3s
│   └── ingress/                   # Cài nginx-ingress controller
├── helm/
│   ├── backend/                   # Shared chart cho 6 NestJS services
│   ├── chatbot/                   # Chart riêng cho chatbot (Python)
│   └── ingress/                   # Ingress routing rules
├── docker-compose/
│   ├── stateful-stack.yml         # PostgreSQL, MongoDB, Redis, Kafka, Keycloak, OmniRoute
│   ├── observability-stack.yml    # SigNoz, LangFuse, ClickHouse, MinIO
│   ├── config/                    # otel-collector-config.yaml
│   └── init-scripts/              # PostgreSQL & MongoDB init scripts
├── .github/workflows/
│   ├── cd-backend.yml             # Reusable: deploy 1 backend service
│   ├── cd-chatbot.yml             # Reusable: deploy chatbot service
│   ├── _example-caller-backend.yml # Template copy vào backend app repo
│   ├── _example-caller-chatbot.yml # Template copy vào chatbot app repo
│   └── README.md                  # Hướng dẫn setup GitHub Actions
└── scripts/
    ├── check-before-commit.sh     # Kiểm tra security trước khi commit
    ├── setup-utm-network.sh       # Cấu hình network UTM local
    └── verify-cluster.sh          # Kiểm tra cluster sau khi provision

Môi trường

Env	Inventory	Nodes	Mục đích
`utm-local`	`inventory/utm`	192.168.64.10/.11/.12	Phát triển local qua UTM (macOS)
`oracle`	`inventory/oracle`	140.238.x.x (masked)	Production trên Oracle Cloud VMs

Quickstart

1. Yêu cầu

# macOS
brew install ansible helm kubectl
pip3 install ansible-lint

# Tạo SSH key cho cluster
ssh-keygen -t ed25519 -f ~/.ssh/utm_k3s -C "utm-k3s"

2. Cấu hình secrets

# Copy template và điền giá trị thật
cp secrets/vault.yml secrets/vault.yml.plain  # chỉ để tham khảo
# Chỉnh sửa secrets/vault.yml, thay tất cả CHANGE_ME
# Sau đó encrypt:
ansible-vault encrypt secrets/vault.yml
ansible-vault encrypt roles/stateful_stack/vars/vault.yml

# Lưu vault password vào file local (không commit)
echo "your-vault-password" > ~/.vault_pass
chmod 600 ~/.vault_pass

3. Provision cluster từ đầu (chạy 1 lần)

# Kiểm tra kết nối SSH
ansible all -i inventory/utm -m ping

# Provision toàn bộ
ansible-playbook -i inventory/utm playbooks/site.yml \
  --vault-password-file ~/.vault_pass

4. Kiểm tra cluster

export KUBECONFIG=~/.kube/football-k3s.yaml
kubectl get nodes
kubectl get pods -n football-booking

CI/CD với GitHub Actions

Deploy tự động khi push code vào app repo:

git push (app repo)
  → GitHub Actions CI: build Docker image → push Docker Hub
  → Gọi reusable workflow từ repo này
  → SSH vào master → helm upgrade --atomic
  → K3s rolling update (tự rollback nếu fail)

Setup chi tiết: .github/workflows/README.md

Deploy thủ công:

ansible-playbook -i inventory/oracle playbooks/deploy_service.yml \
  -e "service=user-service" \
  -e "image_tag=abc1234" \
  --vault-password-file ~/.vault_pass

Security

# Chạy trước mỗi lần git commit
./scripts/check-before-commit.sh

Script kiểm tra: - Vault files đã encrypt chưa - Không có private key content trong tracked files - Không có hardcoded passwords - Không có kubeconfig hoặc .vault_pass bị staged

Quan trọng: secrets/vault.yml phải luôn ở dạng encrypted ($ANSIBLE_VAULT;1.1;AES256) trước khi commit. Xem hướng dẫn chi tiết trong ARCHITECTURE.md.

Tài liệu

File	Nội dung
`docs/ARCHITECTURE.md`	Architecture guide (English)
`docs/ARCHITECTURE.vi.md`	Kiến trúc chi tiết, vai trò từng component (Tiếng Việt)
`docs/READING_GUIDE.md`	Sequential reading & debug map (English)
`docs/READING_GUIDE.vi.md`	Hướng dẫn đọc tuần tự + debug map (Tiếng Việt)
`.github/workflows/README.md`	Setup GitHub Actions CI/CD

Repo	Mô tả
`football-booking-backend-boilerplate`	NestJS microservices (6 services)
`football-booking-chatbot-service`	Python/FastAPI chatbot service