add longhorn

CLAUDE.md

@@ -0,0 +1,243 @@
+# CLAUDE.md — DBIZ Lakehouse trên Kubernetes (full context)
+
+> File ngữ cảnh cho các session sau. Đọc file này là nắm được: đang ở đâu, đã chốt gì,
+> bẫy nào đã gặp, và còn phải làm gì. Cập nhật mục "TRẠNG THÁI" mỗi khi qua một mốc.
+>
+> **Nguyên tắc vàng của cả dự án:** rebuild có chủ đích (sửa nợ dev khi lên K8s),
+> KHÔNG lift-and-shift, KHÔNG đập cái đang chạy. GitOps thuần. Helm + YAML thuần, **KHÔNG Kustomize**.
+> "dev giống prod" = cùng chart, khác values theo env.
+> "Stateful đứng yên, compute di": MinIO (data lake) GIỮ NGUYÊN ngoài K8s, compute di lên K8s trỏ về qua S3.
+
+---
+
+## 0. TL;DR — đang ở đâu (cập nhật: 2026-07-08)
+
+Đang ở **Phase 0 (nền K8s)**, sắp xong. Cụ thể:
+
+- ✅ Resize `/` các node worker — xong.
+- ✅ **Phép thử sinh tử**: pod K8s → MinIO ngoài (.37) — **XANH HOÀN TOÀN** (list + get + put + delete từ trong pod). Đây là rủi ro #1 của cả kế hoạch, đã gỡ.
+- ✅ CPU baseline x86-64-v2 — đã kiểm hết 5 node (xem mục Bẫy #1).
+- ✅ iscsi_tcp + iscsid trên cả 5 VM (prerequisite Longhorn) — xong, module đã ghim tự-load-sau-reboot.
+- ✅ Sealed Secrets controller — đã có sẵn trên cụm (kube-system).
+- ✅ ArgoCD — đã chạy (namespace argocd).
+- ✅ Repo GitOps `dbiz-lake-k8s` — đã có, **public**, đã điền `<REPO_URL>` = `https://git.renolation.com/renolation/dbiz-lake-k8s.git`, đã commit + push.
+- ⏳ **ĐANG LÀM: cài Longhorn** như hạ tầng nền cụm (cách A — tách riêng khỏi envs/<env>/apps). Chưa xong.
+- ⬜ Sau Longhorn: apply root app tầng lake (`envs/dev/apps/root.yaml`).
+
+**Bước kế tiếp ngay:** cài Longhorn qua ArgoCD Application (tầng infra nền cụm), verify StorageClass `longhorn` + PVC survive pod delete. RỒI mới apply root lake stack.
+
+---
+
+## 1. Bối cảnh hạ tầng
+
+### Cụm K8s
+- **5 VM K8s trên 1 host Proxmox.** (Có Proxmox thứ hai cùng mạng → lộ trình HA thật sau này.)
+- Control plane HA, đứng sau VIP/LB tại **`192.168.110.14:8443`** (kubeconfig trỏ vào đây, KHÔNG phải 127.0.0.1:6443).
+- StorageClass hiện tại: `local-path` (default). Sắp thêm `longhorn`.
+- Namespace convention **lakehouse**: `dbiz-lake-dev`, `dbiz-lake-prod`.
+  - (Phân biệt: `dbiz-dev/staging/prod` + `monitoring` là namespace của app **platform** khác, KHÔNG phải lake.)
+
+### Hạ tầng NGOÀI K8s (giữ nguyên, compute trỏ vào qua Service+Endpoints không selector)
+- **MinIO (data lake): VM `lake` = `192.168.110.37:9000`.** Bucket `dbiz-warehouse`. Key `dbiz`/`dbiz1234` (dev — NỢ bảo mật).
+  - Đây là điểm neo dữ liệu xuyên suốt — KHÔNG BAO GIỜ migrate. Toàn bộ compute K8s trỏ về đây như S3 endpoint.
+  - Trong bucket đã có prefix: `raw_crm/`, `raw_posthog/`, `raw_test/`, `results_posthog/`, `staging_posthog/`, vài prefix UUID, và rác `staging_posthog_staging_posthog/`.
+- **Postgres nguồn CRM: `172.20.109.5:5432`** — cho Debezium/Strimzi trỏ tới khi làm CDC (Phase 4). Cần xác nhận đúng là PG nguồn CRM trước khi dùng.
+
+### Git / CI
+- Repo GitOps: **`git.renolation.com/renolation/dbiz-lake-k8s`** (public).
+  - Plan gốc ghi đích cuối là `git.dbiz.com` (Gitea built-in registry) — nhưng "URL là biến số". Đang dùng Renolation, đổi sau = một lệnh sed + cập nhật ArgoCD repo creds.
+- CI: **Woodpecker** (đã có). File `.woodpecker/`. Build + push image spark-cdc.
+- Registry: placeholder `<IMAGE_REGISTRY>` (đích: Gitea built-in). Image cdc-job hiện trỏ `git.dbiz.com/dbiz/spark-cdc` trong values — **cần đổi sang registry Renolation thật khi build image** (chưa làm).
+
+---
+
+## 2. Kiến trúc đích (K8s)
+
+```
+┌──────────────── K8s cluster (5 VM / 1 host Proxmox) ────────────────┐
+│ namespace: dbiz-lake-dev | dbiz-lake-prod                            │
+│                                                                      │
+│ ArgoCD (app-of-apps) ── sync ──► mọi stack                          │
+│                                                                      │
+│ Strimzi(Kafka+Connect+Debezium) · Spark Operator · Trino · Polaris · │
+│ Airflow(K8sExecutor) · dbt · Superset/Metabase · OpenMetadata        │
+│ Longhorn (block PV: Postgres / Kafka / ES / Spark checkpoint)        │
+└──────────────────────────┬───────────────────────────────────────────┘
+                           │ S3 endpoint (qua mạng)
+        ┌──────────────────▼─────────────┐
+        │ MinIO (GIỮ NGUYÊN, ngoài K8s)   │  ← data lake đứng yên
+        │ 192.168.110.37, dbiz-warehouse  │
+        └────────────────────────────────┘
+ Postgres CRM (172.20.109.5) ──► Debezium(Strimzi) bắt CDC
+```
+
+### Stack đích & mô hình chạy
+| Layer | Stack | Ghi chú K8s |
+|-------|-------|-------------|
+| Storage | MinIO | NGOÀI K8s (giữ nguyên), Service+Endpoints `minio-lake` |
+| Table format | Apache Iceberg | thư viện trong engine, không phải service |
+| Catalog (L4) | **Polaris** | chart CHƯA có trong skeleton → thêm app riêng |
+| Engine | Trino, Spark (Spark Operator, SparkApplication CRD) | Spark job = pod ephemeral, image bundled |
+| Ingestion | Strimzi (Kafka+Connect+Debezium) dựng mới trên K8s | chấp nhận snapshot CDC lại (không migrate offset Docker) |
+| Transform | dbt (KubernetesPodOperator) | compute ở Trino |
+| Orchestration | Airflow (K8sExecutor, git-sync DAG) | giải nợ version-control DAG |
+| Consumption | Superset + Metabase | đọc results qua Trino |
+| Governance | OpenMetadata + ES + PG | LÀM SAU CÙNG — version lock mong manh nhất |
+
+> ⚠️ **Lưu ý catalog:** tài liệu ARCHITECTURE.md (bản cũ) ghi **Lakekeeper**, nhưng bản đang chạy thật + mọi tài liệu vận hành/K8s dùng **Apache Polaris 1.5.0**. → **Polaris là bản đúng.**
+
+---
+
+## 3. Quyết định đã chốt (không bàn lại trừ khi có lý do mới)
+
+1. **1 cụm K8s, tách namespace dev/prod.** Helm + values per-env. KHÔNG Kustomize.
+2. **GitOps đầy đủ từ đầu:** ArgoCD (app-of-apps) + Woodpecker CI + Sealed Secrets + cert-manager.
+3. **Secret = Sealed Secrets** (mã hoá, commit an toàn vào git). Giải nợ credential plaintext.
+4. **MinIO GIỮ NGUYÊN ngoài K8s.** Không migrate data lake.
+5. **Longhorn** cho block PV nội cụm (Postgres/Kafka/ES/Spark checkpoint). Không ôm data lake → nhu cầu nhỏ.
+6. **Kafka: Strimzi dựng mới trên K8s** (không xài ké Docker cũ). Snapshot CDC lại.
+7. **Spark: Spark Operator** (SparkApplication CRD), image bundled (jar Iceberg/Kafka sẵn trong image).
+8. **Longhorn cài theo "cách A": hạ tầng nền cụm tách riêng** khỏi `envs/<env>/apps` (nó là singleton toàn cụm, không thuộc riêng dev/prod).
+9. **Multi-tenant — phân biệt 2 loại:**
+   - Tenant trong CRM (data DBIZ) → tách bằng cột `tenantId`, KHÔNG nhân hạ tầng. Lake DBIZ là MỘT.
+   - Khách mua nền tảng (Vietbank/Gemadept) → isolate per khách qua **ApplicationSet**. 3 mức cách ly (M1 chung compute/tách data · M2 tách namespace · M3 isolate hoàn toàn kể cả on-prem).
+10. **"Lakehouse as a product", YAGNI có kỷ luật:** LÀM NGAY = DBIZ lake "khách số 0", tham số hoá sạch (chart nhận customer/source/bucket/s3.endpoint qua values). CHƯA LÀM = ApplicationSet lake, preset 3 mức, đa cụm (thêm khi có khách thứ 2).
+11. **Chart nhận mọi dependency qua values** (S3/nguồn/kafka) — KHÔNG hardcode hạ tầng. Điều kiện để 1 chart phục vụ cả multi-tenant DBIZ lẫn on-prem air-gapped.
+
+### Quyết định cho Longhorn (chốt tại session này)
+- Cài qua **ArgoCD Application** (Helm chart upstream `https://charts.longhorn.io`), GHIM version.
+- **GIỮ `local-path` làm default StorageClass** — Longhorn là StorageClass tường minh, chỉ workload chỉ định `storageClass: longhorn` mới dùng (tránh vô tình đẩy mọi PVC lên Longhorn).
+- **Replica count: đề xuất 2** (không 3). Lý do: 1 host vật lý → 3 replica chỉ "an toàn giả" (mất host mất hết). 2 replica đủ chống node/pod chết, nhẹ hơn; phần còn lại dựa vào backup (đúng mục E rủi ro #2).
+
+---
+
+## 4. Cấu trúc repo `dbiz-lake-k8s`
+
+```
+charts/lake-cdc-job/        Chart CDC job (SparkApplication + checkpoint PVC) — THAM SỐ HOÁ theo customer
+envs/dev/
+  apps/                     ArgoCD Applications (App-of-Apps tầng LAKE)
+    root.yaml               Root → quét envs/dev/apps (path=envs/dev/apps, dest ns=argocd)
+    infra.yaml              → envs/dev/infra (Service+Endpoints ngoài), dest ns=dbiz-lake-dev
+    strimzi-operator.yaml
+    spark-operator.yaml
+    kafka-cluster.yaml      → envs/dev/kafka
+    cdc-job.yaml            chart lake-cdc-job + values
+  infra/external-services.yaml  MinIO ngoài .37 + Postgres CRM .5 (ĐÃ điền IP thật)
+  kafka/kafka.yaml          Strimzi KRaft, Longhorn PV
+  values/cdc-job.yaml       values khách số 0 = dbiz
+  sealed-secrets/           (.gitkeep) — SealedSecrets sẽ để đây
+envs/prod/sealed-secrets/   (.gitkeep)
+images/spark-cdc/Dockerfile FROM spark:3.5.6 + jar Iceberg/Kafka + cdc_crm_to_raw.py
+.woodpecker/                Woodpecker CI
+```
+
+> **SẮP THÊM (Longhorn, cách A):** thư mục tầng nền cụm riêng, ví dụ `infra/cluster/` với `root.yaml` (app-of-apps nền) + `00-longhorn.yaml`. Tách khỏi `envs/<env>/apps`. (Chốt tên chính xác khi làm ở session repo.)
+
+### File values cdc-job (khách số 0 = dbiz) — điểm cần biết
+- `customer: dbiz`, `targetTable: iceberg.raw_crm.cdc_events`, `topicPattern: crm\.public\..*`
+- `catalog.uri: http://polaris:8181/api/catalog`, `warehouse: dbiz_warehouse`
+- `s3.endpoint: http://minio-lake:9000` (Service nội cụm trỏ ra .37), `region: us-east-1`
+- `checkpoint: storageClass=longhorn, size=5Gi` ← **lý do Longhorn phải xong TRƯỚC khi apply root lake**
+- `image.repository: git.dbiz.com/dbiz/spark-cdc` ← **CẦN đổi sang registry Renolation thật**
+- `imagePullSecret: gitea-registry` ← cần seal secret này
+
+---
+
+## 5. Roadmap theo Phase (K8S_MIGRATION_PLAN)
+
+- **Phase 0 — Nền K8s** (đang ở đây): resize `/` ✅ · Longhorn ⏳ · Sealed Secrets ✅ · cert-manager + ingress ⬜ · ArgoCD app-of-apps ✅ (một phần). Verify mạng K8s→MinIO ✅.
+- **Phase 1 — Image & MinIO endpoint:** Dockerfile spark-cdc + Woodpecker build/push ⬜ · SealedSecret minio-creds ⬜. (Verify pod K8s `mc`/`aws s3 ls` bucket ✅ đã làm sớm.)
+- **Phase 2 — State metadata (Longhorn PV):** Postgres K8s (CloudNativePG) — dump Docker → restore K8s. (MinIO không cần.)
+- **Phase 3 — Catalog + Engine:** Polaris (Deployment, chart phải TỰ THÊM) → PG K8s + MinIO ngoài · Spark Operator + Trino (Helm). Verify Trino query Iceberg (data cũ MinIO, catalog Polaris K8s).
+- **Phase 4 — Ingestion CDC (cắt over):** Strimzi (Kafka+Connect+Debezium) PV Longhorn · KafkaConnector Debezium → PG CRM .5 · SparkApplication CDC → `raw_crm.cdc_events`. Verify update ở CRM chảy vào lake. RỒI tắt CDC Docker cũ.
+- **Phase 5-7:** Airflow (K8sExecutor, git-sync) + dbt (KubernetesPodOperator) · Superset + Metabase · OpenMetadata (SAU CÙNG, ghim version chặt).
+- **Phase 8 — Dọn dẹp:** verify toàn hệ ≥ vài ngày, giữ Docker fallback, tắt dần Docker. MinIO vẫn giữ.
+
+---
+
+## 6. Bẫy đã gặp (cheat-sheet — đọc trước khi debug)
+
+1. **x86-64-v2 glibc fatal error.** Image hiện đại (minio/mc mới, aws-cli, sẽ cả Spark/Trino/ClickHouse/ES) build với glibc yêu cầu x86-64-v2. VM Proxmox để CPU type mặc định (`kvm64`/`qemu64`) CHE mất instruction v2 (thiếu sse4_2/popcnt/ssse3/sse4_1). → Sửa gốc: Proxmox `VM→Hardware→Processors→Type` = `host` (perf tối đa) hoặc `x86-64-v2-AES` (an toàn migrate 2 host), rồi **power cycle** (reboot guest không đủ). Kiểm: `lscpu | grep -oE 'sse4_2|popcnt|ssse3|sse4_1'`. **Phải đồng nhất MỌI node** (pod schedule bất kỳ node nào). Vá tạm qua phép thử mạng: pin `minio/mc:RELEASE.2023-11-20T16-30-59Z` (chạy trên v1).
+2. **kubeconfig trỏ VIP `.14:8443`, không phải `127.0.0.1:6443`.** `curl 127.0.0.1:6443/healthz` = ok chỉ chứng minh apiserver LOCAL sống; nếu `kubectl` (qua .14) báo `Unable to connect to the server: EOF` thì VIP/LB đang fail-over. Xảy ra khi power-cycle VM master.
+3. **etcd 3-node: chỉ đụng MỘT master tại một thời điểm.** Đổi CPU/power-cycle tuần tự, đợi node rejoin + quorum ổn rồi mới sang node kế. Tắt 2 master cùng lúc = mất quorum, cả cụm đứng. (Đã thấy restart count etcd/apiserver=5 khi power-cycle — fail-over tạm, tự hồi.)
+4. **Longhorn prerequisite:** `open-iscsi` + `iscsid` active + module `iscsi_tcp` trên MỌI node. Ghim `/etc/modules-load.d/iscsi_tcp.conf` để tự load sau reboot (modprobe tay chỉ tới reboot kế). Thiếu → volume `Pending`/`faulted`.
+5. **ArgoCD đọc git REMOTE, không đọc file local.** Commit mà chưa `git push` → ArgoCD vẫn thấy bản cũ. Luôn push trước khi apply/sync.
+6. **MinIO advertised-endpoint:** `list` (ls) thông KHÔNG chứng minh get/put thông. Phép thử sinh tử phải là put+get+delete object thật TỪ TRONG POD (không phải từ host, không phải ping). Đã test XANH.
+7. **Spark ↔ MinIO cần path-style S3** (không virtual-host style) + executor `-Daws.region=us-east-1` (system property). Nếu Spark fail đọc S3 dù mc OK → nghi path-style/region.
+8. **Iceberg từ chối `timestamp(3)` → phải `timestamp(6)`.**
+9. **Polaris chặn DROP-with-purge** (an toàn prod). Trino/dbt KHÔNG purge được, chỉ Spark `DROP TABLE ... PURGE`. dbt marts phải `+on_table_exists: replace` (dùng CREATE OR REPLACE), nếu không chạy lần 2 fail.
+10. **OpenMetadata version lock** (OM ↔ ES ↔ Airflow-trong-ingestion). ES phải khớp client (OM 1.13.1 → ES 9.3.0). Restart `openmetadata_server` sau khi đổi ES. Scheduler UI hỏng với Airflow 3.2 → ingestion bằng CLI/YAML. → Để SAU CÙNG, ghim version, không auto-latest.
+11. **1 host Proxmox = điểm chết đơn.** HA storage là ảo giác tới khi trải 2 host. Backup thật = Velero (PV/manifest) + pg_dump + mc mirror MinIO → Proxmox 2.
+
+---
+
+## 7. NỢ mang từ bản Docker sang (giải trong lúc rebuild, không dựng lại nền)
+
+- **Bảo mật (nguy hiểm nhất):** creds plaintext (`dbiz1234`, POSTHOG_KEY, JWT trong YAML, `polaris-secret-dev`) → Sealed Secrets. Auth thật cho Trino/Superset/OM/MinIO.
+- **Git-sync DAG:** Airflow DAG đang tạo tay → version control + git-sync (giải khi lên Airflow K8s Phase 5).
+- **Backup:** MinIO + Postgres metadata chưa có backup → Velero + pg_dump + mc mirror.
+- **Monitoring/alert:** Prometheus/Grafana đã dựng, chưa gắn alert DAG fail / data trễ.
+- **Retention Iceberg:** expire snapshots + compaction định kỳ.
+- **Checkpoint Spark:** bản Docker để local FS (không migrate được) → K8s đặt PVC Longhorn/MinIO ngay từ đầu; cắt over = snapshot lại.
+- **Dọn rác:** schema ghép cũ `staging_posthog_staging_posthog`, bảng `*__dbt_backup` — dọn bằng Spark PURGE.
+
+---
+
+## 8. Việc phải làm trước khi apply root lake stack (checklist)
+
+- [x] Điền IP MinIO `.37` vào `external-services.yaml` (đã có sẵn trong file).
+- [x] Điền `<REPO_URL>` = Renolation, commit + push.
+- [x] iscsi trên mọi node (Longhorn prereq).
+- [ ] **Cài Longhorn (đang làm)** — StorageClass `longhorn` xuất hiện + PVC survive pod delete.
+- [ ] Kiểm các Application còn lại (strimzi/spark/kafka) — còn placeholder hay version pin tạm nào không (kiểm bản mới nhất Strimzi/Spark Operator chart, cập nhật targetRevision).
+- [ ] Seal imagePullSecret registry (tên `gitea-registry`) → `envs/dev/sealed-secrets/`.
+- [ ] Đổi `image.repository` cdc-job từ `git.dbiz.com` sang registry Renolation thật.
+- [ ] Dựng Polaris trên K8s (chart CHƯA có trong skeleton — thêm app riêng, Phase 3).
+- [ ] cert-manager + ingress (nếu expose UI) — Phase 0 còn lại.
+
+---
+
+## 9. Lệnh hay dùng
+
+```bash
+# Verify cụm lành
+kubectl get nodes
+kubectl get pods -n kube-system | grep -E 'etcd|apiserver'
+
+# CPU baseline mọi node
+for n in $(kubectl get nodes -o name | sed 's|node/||'); do
+  echo -n "$n: "; ssh k8sadmin@$n "lscpu | grep -oE 'sse4_2|popcnt|ssse3|sse4_1' | tr '\n' ' '"; echo
+done
+
+# Phép thử sinh tử MinIO từ pod (image v1-safe)
+kubectl run mc-test -n dbiz-lake-dev --rm -it --restart=Never \
+  --image=minio/mc:RELEASE.2023-11-20T16-30-59Z \
+  --env="MC_HOST_lake=http://dbiz:dbiz1234@192.168.110.37:9000" \
+  --command -- /bin/sh
+#   mc ls lake/dbiz-warehouse
+#   echo probe > /tmp/p.txt; mc cp /tmp/p.txt lake/dbiz-warehouse/_k8s_probe/p.txt
+#   mc cat lake/dbiz-warehouse/_k8s_probe/p.txt; mc rm lake/dbiz-warehouse/_k8s_probe/p.txt
+
+# StorageClass / Longhorn
+kubectl get storageclass
+kubectl get pods -n longhorn-system
+
+# Đổi REPO_URL toàn repo (nếu chuyển registry/repo)
+grep -rl '<REPO_URL>' . | xargs sed -i 's#<REPO_URL>#<url-mới>#g'
+
+# Bootstrap app-of-apps (ArgoCD đọc remote → push trước!)
+kubectl apply -f envs/dev/apps/root.yaml
+```
+
+---
+
+## 10. Lưu ý cho session sau
+
+- **Luôn push git trước khi apply/sync ArgoCD.**
+- **Không đập cái đang chạy:** CDC Docker cũ giữ chạy tới khi CDC K8s verify xong (Phase 4).
+- **MinIO không bao giờ đụng** — điểm neo dữ liệu.
+- **Mỗi phase verify kỹ mới sang.** "Di toàn bộ" = nhiều tuần.
+- **Version Helm chart (Strimzi/Spark Operator) đang pin TẠM** — kiểm bản mới khi dựng thật.
+- Khi tạo file/manifest cho repo: đưa NỘI DUNG ĐẦY ĐỦ + lệnh git + lệnh verify. GitOps thuần, không helm install tay.
+- Credential dev đang là `dbiz`/`dbiz1234` khắp nơi — đừng đưa vào git dạng plaintext, dùng Sealed Secrets.