🎯 Mục tiêu

Sau Lab này, bạn sẽ có thể:

• Hiểu ArgoCD báo lỗi ở đâu và cách đọc trạng thái Application.
• Troubleshoot các lỗi phổ biến: OutOfSync, SyncFailed, Degraded, Missing.
• Biết cách kiểm tra ArgoCD từ UI và CLI.
• Phân biệt lỗi đến từ Git, ArgoCD hay Kubernetes.
• Thực hiện Rollback khi một deployment gặp sự cố.

---

1. 🤔 Vấn đề thực tế

Hãy tưởng tượng bạn vừa deploy version mới của Todo App.

Developer nói:

"Em đã merge code rồi, nhưng production đang lỗi."

Bạn mở ArgoCD và thấy:

Application: todo-app

Sync Status: OutOfSync
Health Status: Degraded

Hoặc:

Sync Status: Unknown
Health Status: Missing

Hoặc tệ hơn:

Sync Failed

Lúc này câu hỏi không phải là:

"ArgoCD bị lỗi à?"

Mà phải là:

"Lỗi nằm ở Git, ArgoCD hay Kubernetes?"

Đây chính là kỹ năng quan trọng của troubleshooting.

---

2. 🧠 Hiểu nhanh

2.1 🔄 ArgoCD thực sự đang kiểm tra điều gì?

ArgoCD liên tục so sánh:

             Git Repository
                  │
                  │ Desired State
                  ▼
             ┌─────────┐
             │  ArgoCD │
             └────┬────┘
                  │
                  │ Compare
                  ▼
             Kubernetes
                  │
                  │ Actual State
                  ▼

Ví dụ Git yêu cầu:

replicas: 3

Nhưng Kubernetes đang chạy:

replicas: 2

ArgoCD phát hiện:

Desired State != Actual State

và báo:

OutOfSync

💡 Tư duy quan trọng

ArgoCD không đơn giản là:

"Tool để deploy Kubernetes."

Nó giống như một người giám sát:

Git
 │
 │ "Phải chạy như thế này"
 ▼
ArgoCD
 │
 │ "Thực tế đang như thế này"
 ▼
Kubernetes

ArgoCD phát hiện sự khác biệt và có thể sửa lại Kubernetes về đúng trạng thái trong Git.

---

3. 🏗️ Architecture

Trong Lab này, flow troubleshooting sẽ là:

                    Git Repository
                         │
                         │ Desired State
                         ▼
                  ┌──────────────┐
                  │    ArgoCD    │
                  │              │
                  │ Diff         │
                  │ Sync         │
                  │ Health       │
                  └──────┬───────┘
                         │
                         │ Apply
                         ▼
                  ┌──────────────┐
                  │  Kubernetes  │
                  │              │
                  │ Deployment   │
                  │ Service      │
                  │ Pod          │
                  └──────┬───────┘
                         │
                         ▼
                    Application

Khi có lỗi, chúng ta sẽ debug theo hướng:

Application
    │
    ├── Sync Status
    │
    ├── Health Status
    │
    ├── Events
    │
    ├── Diff
    │
    ▼
Kubernetes Resources
    │
    ├── Deployment
    ├── Pod
    ├── Service
    └── ConfigMap / Secret

---

4. 🧰 Chuẩn bị môi trường

Lab này sử dụng Application đã tạo ở các Lab trước.

Kiểm tra ArgoCD:

argocd version

Kiểm tra Kubernetes:

kubectl get nodes

Kiểm tra Application:

argocd app list

Ví dụ:

NAME        CLUSTER                         NAMESPACE   STATUS
todo-app    https://kubernetes.default.svc  todo-app    Synced

Nếu Application đang Synced và Healthy, chúng ta sẽ cố tình tạo lỗi để học troubleshooting.

---

5. 🔍 Troubleshooting Flow

Trước khi đi vào từng lỗi, hãy nhớ flow này:

        ArgoCD Application
                │
                ▼
        ┌─────────────────┐
        │ Sync Status ?   │
        └────────┬────────┘
                 │
       ┌─────────┴─────────┐
       │                   │
    Synced             OutOfSync
                           │
                           ▼
                      Check Diff
                           │
                           ▼
                      Sync Failed?
                           │
                           ▼
                    Check Resources
                           │
                           ▼
                     Check Pod
                           │
                           ▼
                 kubectl describe/logs

Đừng vội chạy hàng chục command.

Hãy xác định trạng thái đang có vấn đề gì trước.

---

6. 🧪 Lab 1 — Troubleshoot OutOfSync

🤔 Vấn đề

Giả sử Kubernetes đang chạy:

replicas: 2

Nhưng Developer thay đổi Git:

replicas: 3

ArgoCD sẽ phát hiện:

Git              Kubernetes

replicas: 3  ≠   replicas: 2

→ OutOfSync

---

🔨 Do

Mở file Deployment trong GitOps repository:

spec:
  replicas: 3

Commit:

git add .
git commit -m "scale todo app to 3 replicas"
git push

Chờ ArgoCD refresh.

Kiểm tra:

argocd app get todo-app

Bạn có thể thấy:

Sync Status: OutOfSync
Health Status: Healthy

---

👀 See Result

Kiểm tra Diff:

argocd app diff todo-app

Bạn sẽ thấy sự khác biệt giữa:

DESIRED
replicas: 3

và:

LIVE
replicas: 2

Đây chính là Diff.

---

🧠 Understand

OutOfSync không nhất thiết có nghĩa là hệ thống đang lỗi.

Nó chỉ có nghĩa:

Kubernetes hiện tại khác với trạng thái mà Git yêu cầu.

Có thể là:

Git changed
    ↓
ArgoCD detects difference
    ↓
OutOfSync

Hoặc:

Someone manually changed Kubernetes
    ↓
Actual State changed
    ↓
OutOfSync

Đây là lý do GitOps hạn chế việc sửa trực tiếp production bằng:

kubectl edit

hoặc:

kubectl scale deployment ...

---

7. 🧪 Lab 2 — Manual Change → ArgoCD Self-Healing

Đây là một tình huống rất thực tế.

🤔 Vấn đề

Một Engineer chạy:

kubectl scale deployment todo-backend \
  -n todo-app \
  --replicas=1

Trong khi Git vẫn yêu cầu:

replicas: 3

Điều gì xảy ra?

---

🔨 Do

Scale deployment:

kubectl scale deployment todo-backend \
  -n todo-app \
  --replicas=1

Kiểm tra:

kubectl get deployment todo-backend -n todo-app

Sau đó:

argocd app get todo-app

Bạn có thể thấy:

Sync Status: OutOfSync

---

👀 See Result

Nếu Application đã bật:

Automated Sync
Self Heal

ArgoCD sẽ phát hiện thay đổi và đưa Deployment về:

replicas: 3

Kiểm tra:

kubectl get deployment todo-backend -n todo-app

---

🧠 Understand

Đây chính là Self-Healing.

        Git
        │
        │ replicas = 3
        ▼
      ArgoCD
        │
        │ detects drift
        ▼
 Kubernetes
 replicas = 1
        │
        │ Self-Heal
        ▼
 replicas = 3

💡 Production Tip

Nếu production có nhiều Engineer:

Git nên là nơi duy nhất thay đổi desired state.

Không nên:

Engineer
   │
   └── kubectl edit production

Mà nên:

Engineer
   │
   ▼
Git Pull Request
   │
   ▼
Review
   │
   ▼
ArgoCD
   │
   ▼
Production

---

8. 🧪 Lab 3 — Troubleshoot SyncFailed

🤔 Vấn đề

OutOfSync nghĩa là:

"Desired State khác Actual State."

Nhưng SyncFailed nghĩa là:

"ArgoCD đã cố gắng apply thay đổi nhưng Kubernetes từ chối."

Ví dụ bạn commit:

spec:
  replicas: 3

Không có vấn đề gì.

Nhưng bạn vô tình tạo một Deployment sai:

spec:
  replicas: abc

Kubernetes không thể tạo resource này.

---

🔨 Do

Sửa Deployment trong Git thành:

spec:
  replicas: abc

Commit:

git add .
git commit -m "test invalid deployment"
git push

Sau đó Sync:

argocd app sync todo-app

---

👀 See Result

Kiểm tra:

argocd app get todo-app

Bạn có thể thấy:

Sync Status: OutOfSync
Health Status: ...
Operation: Failed

Lúc này đừng chỉ nhìn:

Sync Failed

Hãy xem resource nào fail.

argocd app resources todo-app

Hoặc kiểm tra trong ArgoCD UI:

Application
   ↓
Resource Tree
   ↓
Deployment
   ↓
Error / Events

---

🧠 Understand

Flow của SyncFailed thường là:

Git
 │
 │ Invalid manifest
 ▼
ArgoCD
 │
 │ Sync
 ▼
Kubernetes
 │
 X
 │ Reject
 ▼
SyncFailed

Vì vậy khi gặp SyncFailed:

Đừng hỏi:

"ArgoCD tại sao không deploy?"

Hãy hỏi:

"Kubernetes đã từ chối resource nào và tại sao?"

---

9. 🔎 Kiểm tra Kubernetes Resource

Đây là kỹ năng cực kỳ quan trọng.

Giả sử ArgoCD báo:

Deployment: todo-backend
Sync Failed

Kiểm tra:

kubectl get deployment todo-backend -n todo-app

Sau đó:

kubectl describe deployment todo-backend -n todo-app

Đặc biệt chú ý:

Events:

Ví dụ:

FailedCreate
Invalid value

---

10. 🧪 Lab 4 — Troubleshoot Degraded

🤔 Vấn đề

Một Application có thể:

Sync Status: Synced
Health Status: Degraded

Điều này rất dễ gây nhầm.

Synced không có nghĩa là Application đang chạy tốt.

Nó chỉ có nghĩa:

Git State == Kubernetes State

Nhưng Pod có thể vẫn crash.

---

🔨 Do

Tạo một Deployment sử dụng image không tồn tại:

containers:
  - name: backend
    image: todo-backend:not-exist

Commit và push.

Sau đó Sync:

argocd app sync todo-app

---

👀 See Result

Kiểm tra:

argocd app get todo-app

Có thể thấy:

Sync Status: Synced
Health Status: Degraded

Kiểm tra Pod:

kubectl get pods -n todo-app

Ví dụ:

todo-backend-xxxxx   0/1   ImagePullBackOff

---

🧠 Understand

Đây là sự khác nhau rất quan trọng:

                 Git
                  │
                  ▼
              ArgoCD
                  │
           ┌──────┴──────┐
           │             │
       Sync Status   Health Status
           │             │
       "Đúng Git?"   "Có chạy tốt?"
           │             │
          YES           NO

Vì vậy:

Synced + Healthy

→ Tốt.

Synced + Degraded

→ Manifest đã được deploy nhưng application đang có vấn đề.

---

11. 🔥 Troubleshooting Pod

Khi ArgoCD báo Degraded, hãy chuyển xuống Kubernetes.

Bước 1 — Kiểm tra Pod

kubectl get pods -n todo-app

---

Bước 2 — Xem trạng thái chi tiết

kubectl describe pod <pod-name> -n todo-app

---

Bước 3 — Xem logs

kubectl logs <pod-name> -n todo-app

Nếu Pod restart nhiều lần:

kubectl logs <pod-name> \
  -n todo-app \
  --previous

--previous rất hữu ích khi container vừa crash và Kubernetes đã restart nó.

---

12. 🧪 Lab 5 — Troubleshoot Missing

🤔 Vấn đề

ArgoCD có thể báo:

Missing

Điều này thường có nghĩa:

Git yêu cầu resource tồn tại nhưng Kubernetes không còn resource đó.

Ví dụ:

Git
 │
 └── Deployment todo-backend
          │
          ▼
      Kubernetes
          │
          X
      Deployment deleted

---

🔨 Do

Xóa Deployment trực tiếp:

kubectl delete deployment todo-backend -n todo-app

Kiểm tra:

kubectl get deployment -n todo-app

Sau đó xem ArgoCD:

argocd app get todo-app

Nếu Self-Healing được bật, ArgoCD sẽ tạo lại resource.

---

👀 See Result

Kubernetes:

kubectl get deployment -n todo-app

Deployment xuất hiện trở lại.

---

🧠 Understand

Đây tiếp tục là một ví dụ của GitOps:

Git
 │
 │ Deployment MUST exist
 ▼
ArgoCD
 │
 │ Detect missing resource
 ▼
Kubernetes
 │
 │ Recreate
 ▼
Deployment

💡 Production Tip

Đây là lý do Self-Healing rất hữu ích.

Nhưng hãy cẩn thận:

Self-Healing không sửa được một cấu hình sai trong Git.

Nếu Git chứa:

image: todo-backend:broken

ArgoCD có thể liên tục đảm bảo rằng:

broken image

được deploy đúng như Git yêu cầu.

GitOps giúp hệ thống consistent, nhưng không tự đảm bảo rằng configuration trong Git đúng về mặt nghiệp vụ.

---

13. 🧪 Lab 6 — Troubleshoot Repository Error

Không phải lỗi nào cũng nằm ở Kubernetes.

Ví dụ:

ComparisonError

hoặc:

Unable to fetch repository

---

🤔 Vấn đề

ArgoCD cần đọc Git repository để biết:

"Production nên chạy cái gì?"

Nếu ArgoCD không truy cập được Git:

Git Repository
      X
      │
      │ Authentication / Network
      ▼
    ArgoCD

ArgoCD không thể biết desired state mới nhất.

---

🔨 Do

Kiểm tra Application:

argocd app get todo-app

Kiểm tra repository:

argocd repo list

Nếu repository có vấn đề, ArgoCD thường hiển thị error message liên quan đến:

authentication
repository not found
permission denied
connection refused

---

🧠 Understand

Khi gặp repository error, hãy kiểm tra theo thứ tự:

1. Repository URL đúng?
          ↓
2. Repository còn tồn tại?
          ↓
3. Credentials đúng?
          ↓
4. ArgoCD có quyền đọc repository?
          ↓
5. Network có truy cập được Git?

💡 Production Tip

Đừng vội restart ArgoCD khi gặp:

Unable to fetch repository

Restart Pod không sửa được:

Wrong Git credentials

Hãy đọc error message gốc trước.

---

14. 🔄 Lab 7 — Rollback Khi Deployment Lỗi

🤔 Vấn đề

Giả sử:

Version 1
   ↓
Deploy
   ↓
Healthy
   ↓
Version 2
   ↓
Deploy
   ↓
🔥 Production Error

Bạn cần quay về version trước.

Trong GitOps, cách tốt nhất thường là:

Revert Git commit
        ↓
Push
        ↓
ArgoCD detects change
        ↓
Sync
        ↓
Previous version

---

🔨 Do

Xem lịch sử Git:

git log --oneline

Ví dụ:

a82d91f update backend image
91c20aa initial deployment

Revert commit lỗi:

git revert a82d91f

Push:

git push

ArgoCD sẽ phát hiện Git đã quay về configuration trước đó.

---

👀 See Result

Kiểm tra:

argocd app get todo-app

Sau khi Sync:

Sync Status: Synced
Health Status: Healthy

---

🧠 Understand

Trong GitOps:

Rollback tốt nhất thường là rollback Git.

Thay vì:

kubectl manually change production

hãy:

Git revert
    ↓
ArgoCD
    ↓
Kubernetes

Lợi ích:

• Có history.
• Có audit trail.
• Team biết ai rollback.
• Trạng thái Git và Kubernetes tiếp tục đồng bộ.

---

15. 🧰 Bộ lệnh Troubleshooting cần nhớ

Không cần học thuộc hàng chục command.

Chỉ cần nhớ nhóm lệnh này:

🔍 ArgoCD

argocd app list

Xem toàn bộ Application.

argocd app get todo-app

Xem trạng thái chi tiết.

argocd app diff todo-app

Xem Git và Kubernetes khác nhau ở đâu.

argocd app resources todo-app

Xem các Kubernetes resources mà Application quản lý.

argocd app sync todo-app

Sync thủ công.

---

☸️ Kubernetes

kubectl get pods -n todo-app

kubectl describe pod <pod> -n todo-app

kubectl logs <pod> -n todo-app

kubectl logs <pod> -n todo-app --previous

kubectl get events -n todo-app

Đây là nhóm command bạn sẽ sử dụng rất nhiều khi troubleshoot production.

---

16. 🧭 Troubleshooting Cheat Sheet

Khi gặp lỗi, hãy bắt đầu từ bảng này:

ArgoCD Status	Ý nghĩa	Kiểm tra tiếp
Synced	Git = Kubernetes	Kiểm tra Health
OutOfSync	Git ≠ Kubernetes	argocd app diff
SyncFailed	Sync không thành công	Resource + Events
Degraded	Resource không khỏe	Pod + Logs
Missing	Resource Git yêu cầu nhưng không tồn tại	kubectl get
Unknown	ArgoCD không xác định được trạng thái	Repository / Controller
ComparisonError	Không thể so sánh Desired/Live	Git / Manifest / Repo
ImagePullBackOff	Không pull được image	Image / Registry / Secret
CrashLoopBackOff	Container liên tục crash	Logs
Pending	Pod chưa được schedule	Resources / Node / PVC

---

17. 🧠 Mental Model Quan Trọng Nhất

Khi troubleshoot ArgoCD, đừng nhìn mọi thứ như một lỗi duy nhất.

Hãy chia thành 3 tầng:

┌─────────────────────────────┐
│          Git                │
│                             │
│ Repository                  │
│ YAML / Helm / Kustomize     │
└──────────────┬──────────────┘
               │
               ▼
┌─────────────────────────────┐
│          ArgoCD             │
│                             │
│ Repository                  │
│ Diff                        │
│ Sync                        │
│ Application Controller      │
└──────────────┬──────────────┘
               │
               ▼
┌─────────────────────────────┐
│       Kubernetes            │
│                             │
│ Deployment                  │
│ Pod                         │
│ Service                     │
│ ConfigMap / Secret          │
└─────────────────────────────┘

Khi có lỗi:

🟢 Tầng 1 — Git

Hỏi:

"Manifest trong Git có đúng không?"

---

🟡 Tầng 2 — ArgoCD

Hỏi:

"ArgoCD có đọc được Git và Sync được không?"

---

🔴 Tầng 3 — Kubernetes

Hỏi:

"Kubernetes có chạy được configuration đó không?"

---

18. 💡 Production Tips

18.1 🚫 Đừng sửa Production bằng kubectl rồi quên Git

Ví dụ:

kubectl edit deployment todo-backend

Bạn có thể sửa được.

Nhưng sau đó:

Git        → replicas: 3
Kubernetes → replicas: 5

ArgoCD:

OutOfSync

Hãy sửa Git thay vì sửa trực tiếp Kubernetes.

---

18.2 🔎 Đừng chỉ nhìn Sync Status

Một Application:

Synced

vẫn có thể:

Degraded

Luôn kiểm tra cả:

Sync Status
+
Health Status

---

18.3 📋 Đọc Events trước khi đoán

Khi Pod lỗi:

kubectl describe pod <pod> -n todo-app

Sau đó xem:

Events

Rất nhiều lỗi Kubernetes có nguyên nhân rõ ràng ngay tại đây:

FailedScheduling
FailedMount
FailedPull
Unhealthy
BackOff

---

18.4 🧠 Error message thường đã nói cho bạn nguyên nhân

Ví dụ:

ImagePullBackOff

Đừng tìm:

"ArgoCD ImagePullBackOff fix"

Hãy chuyển xuống Kubernetes:

kubectl describe pod ...

và tìm:

Failed to pull image

Troubleshooting tốt không phải là biết thật nhiều command.

Nó là khả năng:

đọc trạng thái → xác định tầng lỗi → kiểm tra đúng component.

---

19. 🏁 Tổng kết Lab

Trong Lab này, chúng ta đã cố tình tạo và xử lý nhiều lỗi phổ biến:

OutOfSync
    ↓
Diff
    ↓
SyncFailed
    ↓
Degraded
    ↓
Missing
    ↓
Repository Error
    ↓
Rollback

Điều quan trọng nhất cần nhớ:

                 Git
                  │
            Desired State
                  │
                  ▼
               ArgoCD
                  │
            Sync / Compare
                  │
                  ▼
             Kubernetes
                  │
             Actual State

Khi có vấn đề, hãy đi theo flow:

1. Application đang trạng thái gì?
              ↓
2. Git và Kubernetes khác nhau ở đâu?
              ↓
3. ArgoCD Sync có thành công không?
              ↓
4. Resource nào đang lỗi?
              ↓
5. Kubernetes báo gì?
              ↓
6. Pod logs / Events nói gì?
              ↓
7. Sửa nguyên nhân ở đúng tầng

💡 Rule of thumb: ArgoCD cho bạn biết "có vấn đề ở đâu", còn Kubernetes thường cho bạn biết "tại sao".

---

20. 🚀 Bước tiếp theo

Đến đây bạn đã biết cách deploy và troubleshoot Application bằng ArgoCD.

Nhưng khi hệ thống có:

Dev
Staging
Production

việc tạo từng Application thủ công sẽ nhanh chóng trở nên khó quản lý.

Lab tiếp theo sẽ giải quyết vấn đề đó bằng:

ApplicationSet — tự động quản lý nhiều Application và nhiều Environment với ArgoCD.