ArgoCD Guide — Football Booking GitOps

Hướng dẫn đầy đủ để setup, vận hành và debug hệ thống GitOps với ArgoCD.

1. Prerequisites

Trước khi bắt đầu, đảm bảo đã có:

K3s cluster đang chạy (4 VMs đã setup bằng Ansible)
kubectl đã cấu hình trỏ vào cluster
helm >= 3.12
GitHub Organization và 4 repos đã tạo
GitHub Personal Access Token (PAT) với scope repo

2. Cài đặt ArgoCD

Bước 2.1 — Chạy Ansible playbook

cd football-booking-infras

# Cài ArgoCD lên K3s master
ansible-playbook playbooks/argocd.yml -i inventory/hosts.yml

Bước 2.2 — Verify ArgoCD đang chạy

kubectl get pods -n argocd

Kết quả mong đợi:

NAME                                                READY   STATUS    RESTARTS
argocd-application-controller-0                     1/1     Running   0
argocd-applicationset-controller-xxx                1/1     Running   0
argocd-dex-server-xxx                               1/1     Running   0
argocd-redis-xxx                                    1/1     Running   0
argocd-repo-server-xxx                              1/1     Running   0
argocd-server-xxx                                   1/1     Running   0

Bước 2.3 — Lấy mật khẩu admin lần đầu

kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 -d && echo

Đăng nhập tại http://argocd.football-booking.local với user admin.

Quan trọng: Đổi mật khẩu ngay sau lần đăng nhập đầu tiên. Settings → User Info → Update Password

3. Setup GitHub Secrets

Cần tạo secrets trong mỗi app repo (football-booking-backend-k3s, football-booking-chatbot-service-k3s).

Bước 3.1 — Tạo GitHub PAT

GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens
Repository access: chọn football-booking-gitops
Permissions: Contents → Read and write
Copy token

Bước 3.2 — Thêm secret vào từng repo

Repo Settings → Secrets and variables → Actions → New repository secret

Name:  GITOPS_TOKEN
Value: <token vừa tạo>

Làm cho cả 2 repos: - football-booking-backend-k3s - football-booking-chatbot-service-k3s

4. Thay thế YOUR_GITHUB_ORG

Tìm và thay toàn bộ YOUR_GITHUB_ORG bằng tên GitHub Organization thật:

# Trong repo football-booking-gitops
grep -r "YOUR_GITHUB_ORG" . --include="*.yaml" --include="*.yml" -l

# Thay bằng org thật (ví dụ: football-booking)
find . -type f \( -name "*.yaml" -o -name "*.yml" \) \
  -exec sed -i '' 's/YOUR_GITHUB_ORG/football-booking/g' {} +

5. Deploy ApplicationSet lên ArgoCD

Bước 5.1 — Apply namespace và ApplicationSets

cd football-booking-gitops

kubectl apply -f argocd/namespace.yaml
kubectl apply -f argocd/applicationset-backend.yaml
kubectl apply -f argocd/applicationset-chatbot.yaml

Bước 5.2 — Verify ApplicationSet đã tạo Applications

kubectl get applicationsets -n argocd
kubectl get applications -n argocd

Kết quả mong đợi — ArgoCD tự tạo 1 Application cho mỗi service:

NAME                   SYNC STATUS   HEALTH STATUS
api-gateway            Synced        Healthy
user-service           Synced        Healthy
field-service          Synced        Healthy
booking-service        Synced        Healthy
payment-service        Synced        Healthy
notification-service   Synced        Healthy
chatbot-service        Synced        Healthy

6. Setup Kubernetes Secrets

ArgoCD deploy pods nhưng pods cần secrets để kết nối database, Kafka, etc.

Tạo backend-secrets

kubectl create secret generic backend-secrets \
  --namespace=football-booking \
  --from-literal=DATABASE_URL="postgresql://user:pass@postgres:5432/football" \
  --from-literal=KAFKA_BROKER="kafka:9092" \
  --from-literal=REDIS_URL="redis://redis:6379" \
  --from-literal=JWT_SECRET="your-jwt-secret"

Tạo chatbot-secrets

kubectl create secret generic chatbot-secrets \
  --namespace=football-booking \
  --from-literal=MONGODB_URL="mongodb://mongo:27017/chatbot" \
  --from-literal=OPENAI_API_KEY="sk-..."

7. CI/CD Flow — End-to-End

Luồng deploy backend service mới

1. Developer push code vào football-booking-backend-k3s (branch main)
        │
        ▼
2. GitHub Actions (cd.yml) chạy:
   - Detect: apps/booking-service/** thay đổi
   - Build Docker image
   - Push: ghcr.io/ORG/booking-service:abc1234
        │
        ▼
3. CI commit vào football-booking-gitops:
   envs/production/backend/booking-service.yaml
     image.tag: "abc1234"
        │
        ▼
4. ArgoCD phát hiện thay đổi trong gitops repo (~3 phút polling)
        │
        ▼
5. ArgoCD sync: Helm render chart + apply lên K3s
        │
        ▼
6. Pod mới chạy với image abc1234 ✓

Trigger manual sync (không cần đợi 3 phút)

# CLI
argocd app sync booking-service

# Hoặc trong ArgoCD UI: click nút "Sync"

8. Thêm service mới

Để thêm openclaw vào GitOps, chỉ cần:

# 1. Tạo file values mới
cat > envs/production/backend/openclaw.yaml << EOF
appName: openclaw

image:
  repository: ghcr.io/YOUR_GITHUB_ORG/openclaw
  tag: "latest"

service:
  port: 8888
  targetPort: 8888

ingress:
  enabled: false

replicaCount: 1

envFrom:
  - secretRef:
      name: backend-secrets

namespace: football-booking

healthCheck:
  path: /health
  initialDelaySeconds: 30
  periodSeconds: 10
EOF

# 2. Commit và push
git add envs/production/backend/openclaw.yaml
git commit -m "feat: add openclaw service to GitOps"
git push

ArgoCD tự động phát hiện file mới và tạo Application openclaw. Không cần chỉnh sửa ApplicationSet.

9. Rollback

Rollback bằng git (cách GitOps)

# Xem lịch sử deploy của 1 service
git log --oneline -- envs/production/backend/booking-service.yaml

# Rollback về commit trước
git revert <commit-hash>
git push
# ArgoCD tự sync về image tag cũ

Rollback nhanh bằng ArgoCD CLI

# Xem lịch sử
argocd app history booking-service

# Rollback về revision cụ thể
argocd app rollback booking-service <revision-id>

10. Monitoring & Debug

Kiểm tra trạng thái tổng quan

# Tất cả applications
kubectl get applications -n argocd

# Chi tiết 1 application
argocd app get booking-service

# Events của application
kubectl describe application booking-service -n argocd

Pod không start được

# Xem logs pod
kubectl logs -n football-booking deployment/booking-service --previous

# Xem events namespace
kubectl get events -n football-booking --sort-by='.lastTimestamp'

# Describe pod để xem lỗi
kubectl describe pod -n football-booking -l app.kubernetes.io/name=booking-service

ArgoCD OutOfSync

# Xem diff giữa Git và cluster
argocd app diff booking-service

# Force sync (bỏ qua diff check)
argocd app sync booking-service --force

Image pull error (GHCR private)

# Tạo imagePullSecret
kubectl create secret docker-registry ghcr-secret \
  --namespace=football-booking \
  --docker-server=ghcr.io \
  --docker-username=YOUR_GITHUB_USERNAME \
  --docker-password=YOUR_GITHUB_PAT

Sau đó thêm vào charts/backend-service/templates/deployment.yaml:

spec:
  imagePullSecrets:
    - name: ghcr-secret

11. ArgoCD CLI — Các lệnh thường dùng

# Login
argocd login argocd.football-booking.local --username admin

# List tất cả apps
argocd app list

# Sync tất cả apps
argocd app sync --selector app.kubernetes.io/part-of=football-booking

# Xem logs sync
argocd app logs booking-service

# Disable auto-sync tạm thời (để debug)
argocd app set booking-service --sync-policy none

# Re-enable auto-sync
argocd app set booking-service --sync-policy automated

12. Cấu trúc Branch (nếu muốn thêm staging)

Để thêm môi trường staging trong tương lai:

envs/
├── production/
│   ├── backend/
│   └── chatbot/
└── staging/            ← thêm folder này
    ├── backend/
    └── chatbot/

Tạo thêm argocd/applicationset-backend-staging.yaml với: - path: "envs/staging/backend/*.yaml" - namespace: football-booking-staging