pos-system/docs/vi/guides/kubernetes-local.md

Hướng Dẫn Deploy Kubernetes Local

Hướng dẫn triển khai Kubernetes cục bộ với Docker Desktop trên macOS

Quy Trình Deploy

graph TD
 Start([ Bắt đầu]) --> EnvPrep[1. Chuẩn bị Môi trường]
 EnvPrep --> BuildImg[2. Build Docker Image]
 BuildImg --> LoadImg[3. Load Image vào Cluster]
 LoadImg --> Secrets[4. Cấu hình Secrets & Environment]
 Secrets --> Deploy[5. Deploy Service]
 Deploy --> Verify[6. Kiểm tra & Verify]
 Verify --> Test[7. Test Service]
 Test --> End([ Hoàn tất])

 subgraph "Chi tiết Deploy"
 Deploy --> |Apply| ConfigMap[ConfigMap]
 Deploy --> |Apply| Deployment[Deployment]
 Deploy --> |Apply| Service[Service]
 end

 style Start fill:#1a1a2e,color:#fff
 style End fill:#0f3460,color:#fff
 style EnvPrep fill:#16213e,color:#fff
 style BuildImg fill:#1a1a40,color:#fff
 style LoadImg fill:#1a1a40,color:#fff
 style Secrets fill:#0f4c75,color:#fff
 style Deploy fill:#3282b8,color:#fff
 style Verify fill:#3282b8,color:#fff
 style Test fill:#3282b8,color:#fff
 style ConfigMap fill:#16213e,color:#fff
 style Deployment fill:#16213e,color:#fff
 style Service fill:#16213e,color:#fff

Tổng Quan

Hướng dẫn này mô tả chi tiết cách deploy IAM Service (hoặc bất kỳ microservice nào trong hệ sinh thái GoodGo) lên local Kubernetes cluster sử dụng Docker Desktop trên macOS.

Lưu ý: Hướng dẫn này giả định bạn đang sử dụng Docker Desktop với Kubernetes enabled. Nếu bạn sử dụng Minikube hoặc Kind thuần, các bước có thể hơi khác một chút (đặc biệt là phần load image).

1. Yêu Cầu

Phần Mềm

• Docker Desktop 4.0+: Download Link
• Kubernetes phải được enable trong settings.
• kubectl CLI: Công cụ dòng lệnh để tương tác với K8s.

brew install kubectl

• kind CLI: Cần thiết để load images vào cluster nếu dùng Kind backend (mặc định cho dev).

brew install kind

• pnpm 8+: Package manager của dự án.

npm install -g pnpm

Kiến Thức

• Hiểu cơ bản về các khái niệm Kubernetes: Pod, Deployment, Service, Secret, ConfigMap.
• Quen thuộc với các lệnh Docker cơ bản (docker build, docker images).
• Biết cách điều hướng và chạy lệnh trong Terminal.

2. Chuẩn Bị Môi Trường

2.1 Enable Kubernetes trong Docker Desktop

1. Mở Docker Desktop.
2. Nhấn vào biểu tượng Settings ().
3. Chọn tab Kubernetes.
4. Check vào ô Enable Kubernetes.
5. Chọn Show system containers (advanced) để dễ debug (tùy chọn).
6. Nhấn Apply & Restart.
7. Đợi 2-3 phút cho đến khi icon Kubernetes ở góc dưới chuyển sang màu xanh lá.

2.2 Verify Kubernetes Connection

Kiểm tra xem kubectl đã kết nối đúng context chưa:

# Kiểm tra context hiện tại
kubectl config current-context
# Output mong đợi: docker-desktop

# Liệt kê các node trong cluster
kubectl get nodes
# Output mong đợi:
# NAME STATUS ROLES AGE VERSION
# docker-desktop Ready control-plane 10m v1.29.1

3. Build Docker Image

Chúng ta cần build image của service trước khi deploy. Ở đây lấy ví dụ là iam-service.

# Di chuyển đến thư mục deployments/local/kubernetes
cd deployments/local/kubernetes

# Build Docker image từ root context
# Lưu ý: -f trỏ đến Dockerfile của service, context là root (../../..)
docker build -t iam-service:local -f ../../../services/iam-service/Dockerfile ../../..

# Kiểm tra image đã build thành công chưa
docker images | grep iam-service
# Output mong đợi:
# iam-service local [IMAGE_ID] [SIZE] [CREATED]

4. Load Image vào Cluster

** QUAN TRỌNG**: Docker Desktop có thể sử dụng các backend khác nhau. Nếu bạn đang chạy Kubernetes trong Docker Desktop, đôi khi nó không nhìn thấy image local ngay lập tức nếu sử dụng kind node dưới nền.

Nếu bạn dùng Kind (Kubernetes in Docker) riêng biệt hoặc cấu hình Docker Desktop đặc biệt, bạn cần load image:

# Load image vào kind cluster (nếu dùng kind rõ ràng)
kind load docker-image iam-service:local --name desktop

# Kiểm tra sự tồn tại của image (tùy chọn)

Mẹo: Với Docker Desktop mặc định, việc build image local (docker build ...) thường tự động khả dụng cho K8s cluster của Docker Desktop. Bước load này chủ yếu dành cho ai dùng kind CLI để tạo cluster riêng.

5. Cấu Hình Secrets & ConfigMap

Môi trường Kubernetes cần các biến môi trường nhạy cảm (Secrets) và cấu hình chung (ConfigMap).

5.1 Tạo Secrets (Thủ công)

Bạn có thể chạy script hoặc lệnh sau để tạo secrets an toàn.

# Tạo namespace riêng cho local testing
kubectl create namespace iam-local

# Tạo secrets ngẫu nhiên và lưu vào Kubernetes
kubectl create secret generic iam-service-secrets \
 --from-literal=DATABASE_URL="postgresql://user:password@host.docker.internal:5432/iam_db?schema=public" \
 --from-literal=JWT_SECRET="$(openssl rand -base64 32)" \
 --from-literal=JWT_REFRESH_SECRET="$(openssl rand -base64 32)" \
 --from-literal=ENCRYPTION_KEY="$(openssl rand -base64 32)" \
 -n iam-local

# Kiểm tra secrets đã tạo
kubectl get secrets -n iam-local

Lưu ý về host.docker.internal: Trên macOS, để pod trong K8s kết nối được với PostgreSQL chạy trên máy host (hoặc container khác qua port mapping), ta dùng host.docker.internal.

5.2 ConfigMap

File iam-service-configmap.yaml thường chứa các biến không nhạy cảm như NODE_ENV, LOG_LEVEL.

# Apply ConfigMap
kubectl apply -f iam-service-configmap.yaml -n iam-local

6. Deploy Service

Bây giờ chúng ta sẽ deploy các resource chính.

# Apply file Deployment manifest
kubectl apply -f iam-service-deployment.yaml -n iam-local

# Apply file Service manifest
kubectl apply -f iam-service-service.yaml -n iam-local

7. Verify & Debug

Sau khi deploy, cần đảm bảo Pod đang chạy ổn định (Running).

7.1 Kiểm tra Pods

# Lấy danh sách pod trong namespace
kubectl get pods -n iam-local

# Output mong đợi:
# NAME READY STATUS RESTARTS AGE
# iam-service-68994fdc79-gh2mj 1/1 Running 0 30s

7.2 Xem Logs Chi Tiết

Nếu Status không phải Running (ví dụ CrashLoopBackOff hoặc ImagePullBackOff), hãy xem logs:

# Xem logs thời gian thực từ pod
kubectl logs -f -n iam-local -l app=iam-service

# Xem chi tiết pod để check events (lỗi pull, mount, scheduling)
kubectl describe pod -n iam-local -l app=iam-service

7.3 Lỗi Thường Gặp

1. ImagePullBackOff:

• Lý do: K8s không tìm thấy image iam-service:local.
• Fix: Đảm bảo imagePullPolicy: IfNotPresent hoặc Never trong file yaml deployment local. Nếu dùng Kind, nhớ chạy lệnh kind load.

2. CrashLoopBackOff:

• Lý do: Lỗi runtime, thường là không kết nối được Database.
• Fix: Check biến DATABASE_URL trong Secret. Đảm bảo Postgres đang chạy và accessible từ K8s (dùng host.docker.internal).

3. Pending Service:

• Lý do: Type LoadBalancer trên local đôi khi mãi pending IP.
• Fix: Không sao cả, chúng ta có thể dùng port-forward hoặc truy cập qua localhost.

8. Test Service Access

Để truy cập service từ máy local, cách an toàn nhất là dùng port-forward.

# Port forward từ cổng local 5002 tới cổng 80 của service
kubectl port-forward svc/iam-service 5002:80 -n iam-local

# Terminal sẽ treo và hiện: Forwarding from 127.0.0.1:5002 -> 8000

Mở terminal khác và test:

# Test Health Check
curl http://localhost:5002/health/live
# Response: {"status":"ok", ...}

# Xem tài liệu Swagger/OpenAPI (nếu bật)
open http://localhost:5002/api-docs

9. Cleanup

Khi hoàn tất, hãy xóa resources để giải phóng tài nguyên.

# Xóa namespace (xóa tất cả resource bên trong)
kubectl delete namespace iam-local

---

Quick Tips

Các Vấn Đề Thường Gặp & Giải Pháp

Vấn đề	Triệu chứng	Giải pháp
ImagePullBackOff	Pod bị kẹt ở trạng thái ImagePullBackOff	Đặt imagePullPolicy: Never trong deployment YAML Chạy kind load docker-image nếu dùng Kind
CrashLoopBackOff	Pod liên tục restart	Kiểm tra logs với kubectl logs Verify DATABASE_URL trong secrets Đảm bảo DB accessible qua host.docker.internal
Pending LoadBalancer	Service External-IP hiển thị <pending>	Bình thường trên local—dùng kubectl port-forward thay thế
Connection Refused	Không kết nối được sau port-forward	Kiểm tra pod đang Running (không phải CrashLoopBackOff) Verify port mapping chính xác

Tham Chiếu Lệnh Thiết Yếu

# Debugging
kubectl get pods -n iam-local -w # Theo dõi pods real-time
kubectl describe pod <POD_NAME> -n iam-local # Thông tin chi tiết pod + events
kubectl logs -f <POD_NAME> -n iam-local # Stream logs
kubectl exec -it <POD_NAME> -n iam-local -- /bin/sh # Shell vào container

# Quản Lý Image
docker build -t service:local -f Dockerfile . # Build image
kind load docker-image service:local --name desktop # Load vào Kind cluster
docker images | grep service # Liệt kê local images

# Deploy Nhanh
kubectl apply -f deployment.yaml -n iam-local # Deploy single manifest
kubectl apply -f . -n iam-local # Deploy tất cả files trong thư mục
kubectl rollout restart deployment/iam-service -n iam-local # Force restart pods

# Cleanup
kubectl delete pod <POD_NAME> -n iam-local --force # Force delete pod bị kẹt
kubectl delete namespace iam-local --force --grace-period=0 # Force delete namespace

Deployment Checklist

• Docker Desktop Kubernetes enabled
• kubectl context = docker-desktop
• Image built locally: docker images | grep iam-service
• Namespace created: kubectl get ns iam-local
• Secrets created: kubectl get secrets -n iam-local
• ConfigMap applied: kubectl get cm -n iam-local
• Deployment applied: kubectl get deploy -n iam-local
• Service created: kubectl get svc -n iam-local
• Pods running: kubectl get pods -n iam-local
• Port-forward works: kubectl port-forward ...
• Health check passes: curl http://localhost:5002/health/live

Resource Management

Recommended Resources per Pod:

resources:
 requests:
 memory: "256Mi"
 cpu: "250m"
 limits:
 memory: "512Mi"
 cpu: "500m"

Check Resource Usage:

# Overall cluster resources
kubectl top nodes

# Pod resource usage
kubectl top pods -n iam-local

# Detailed pod metrics
kubectl describe node docker-desktop

Best Practices

1. Sử dụng namespaces để tách biệt môi trường
2. Set resource limits cho mọi pod
3. Use health checks (liveness & readiness probes)
4. Tag images với version cụ thể, không dùng :latest
5. Store secrets trong Kubernetes Secrets, không hardcode
6. Use ConfigMaps cho configuration
7. Enable logging để dễ debug
8. Regular cleanup các resources không dùng

Trạng Thái Visual

• Running - Service hoạt động bình thường
• Pending - Đang chờ resources
• CrashLoopBackOff - Service liên tục fail (kiểm tra logs!)
• ContainerCreating - Pod đang khởi động
• Terminating - Pod đang tắt

Pro Tips

1. ** Fast Rebuild**: Để iterate nhanh, dùng kubectl rollout restart deployment/iam-service -n iam-local sau khi rebuild image
2. ** Watch Mode**: Dùng flag -w để theo dõi resources update real-time
3. ** YAML Validation**: Chạy kubectl apply --dry-run=client -f file.yaml để validate trước khi apply
4. ** Label Filtering**: Dùng -l app=iam-service để filter resources theo label thay vì gõ pod names

Tài Liệu Tham Khảo

• Kubernetes Documentation
• Docker Desktop for Mac
• Prisma Deployment Guide
• kubectl Cheat Sheet
• Kubernetes Best Practices