Sổ tay kỹ thuật

Argo CD – GitOps với Application, sync policy, App of Apps

how-to#kubernetes#gitops#argocd· cập nhật 2026-11-07

Dùng khi muốn Git là nguồn sự thật cho manifest Kubernetes, Argo CD tự đồng bộ cluster theo repo, và cần biết cách rollback an toàn.

Sửa trang này
Mục lục

Tóm tắt: Cài Argo CD vào namespace argocd, khai báo mỗi ứng dụng bằng một CRD Application (repo + path + cluster đích). syncPolicy.automated với prune và selfHeal để cluster luôn khớp Git. Nhiều app thì dùng App of Apps: một Application gốc trỏ tới thư mục chứa các Application con. Rollback đúng kiểu GitOps là git revert; argocd app rollback chỉ là biện pháp tạm.

Luồng hoạt động

flowchart LR
  G["Git repo (manifest)"] -->|"poll / webhook"| R["repo-server render"]
  R --> C["application-controller so sánh"]
  C -->|"OutOfSync"| S["Sync (kubectl apply)"]
  S --> K["Cluster đích"]
  K -->|"live state"| C
  C --> H["Synced + Healthy"]

Argo CD so sánh trạng thái mong muốn (render từ Git: plain YAML, Helm, Kustomize) với live state. Hai trạng thái chính: Sync (Synced/OutOfSync) và Health (Healthy/Progressing/Degraded/Missing).

Cấu hình

Cài đặt và đăng nhập

kubectl create namespace argocd
kubectl apply -n argocd --server-side --force-conflicts \
  -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
kubectl get pods -n argocd
 
# mật khẩu admin ban đầu (xoá Secret này sau khi đổi mật khẩu)
argocd admin initial-password -n argocd
kubectl port-forward svc/argocd-server -n argocd 8080:443
argocd login localhost:8080 --username admin --insecure

stable là branch theo bản phát hành mới nhất; môi trường thật nên ghim theo tag phiên bản. --insecure ở đây chỉ vì port-forward dùng cert tự ký; production đặt Ingress + TLS (xem ingress-nginx + cert-manager).

Application

apps/web.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: web
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  source:
    repoURL: https://git.example.com/platform/deploy.git
    targetRevision: main
    path: web/overlays/prod
  destination:
    server: https://kubernetes.default.svc
    namespace: web
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
Trường Ý nghĩa
source.path Thư mục trong repo; Argo CD tự nhận Helm chart / Kustomize / YAML thường
targetRevision Branch, tag hoặc commit. Ghim tag/commit cho prod nếu cần kiểm soát chặt
destination.server https://kubernetes.default.svc là cluster chứa Argo CD; cluster khác thêm bằng argocd cluster add
automated.prune Xoá resource không còn trong Git
automated.selfHeal Tự đưa về như Git khi có người sửa tay trên cluster
CreateNamespace=true Tự tạo namespace đích
finalizer resources-finalizer... Xoá Application thì xoá luôn resource con (cascade). Bỏ finalizer nếu chỉ muốn gỡ app khỏi Argo CD

Repo private: argocd repo add https://git.example.com/platform/deploy.git --username ci --password "$GIT_TOKEN" (hoặc dùng SSH key); không commit token vào Git.

App of Apps

Một Application gốc trỏ tới thư mục chứa các file Application con; thêm app mới chỉ cần thêm một file YAML vào Git.

deploy/
  root/            # thư mục mà app gốc theo dõi
    web.yaml       # Application
    monitoring.yaml
  web/overlays/prod/...
root-app.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: root
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://git.example.com/platform/deploy.git
    targetRevision: main
    path: root
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
kubectl apply -n argocd -f root-app.yaml    # bootstrap một lần duy nhất

Cần sinh nhiều app theo danh sách cluster/thư mục thì xem ApplicationSet (cùng dự án Argo CD).

Lệnh thường dùng

Mục đích Lệnh
Danh sách app argocd app list
Trạng thái chi tiết argocd app get web
Xem khác biệt Git vs cluster argocd app diff web
Sync thủ công argocd app sync web
Sync thử, không áp dụng argocd app sync web --dry-run
Lịch sử sync (lấy ID) argocd app history web
Rollback về một ID argocd app rollback web <ID>
Tắt auto-sync argocd app set web --sync-policy none
Bật lại auto-sync argocd app set web --sync-policy automated --auto-prune --self-heal
Xoá app (cascade) argocd app delete web

Rollback

  • Cách đúng: git revert <commit> rồi push; Argo CD sync lại. Git vẫn là nguồn sự thật, có audit trail.
  • Khẩn cấp: argocd app rollback không chạy khi automated đang bật. Tắt auto-sync, rollback, điều tra, rồi sửa Git và bật lại; nếu quên thì lần sync kế sẽ đè rollback.

Bật prune: true cùng selfHeal: true nghĩa là xoá/sửa tay trên cluster bị hoàn tác ngay. Với resource nhạy cảm (PVC, namespace) cân nhắc annotation argocd.argoproj.io/sync-options: Prune=false trên resource đó.

Lỗi thường gặp

Triệu chứng Nguyên nhân Cách xử lý
OutOfSync mãi dù vừa sync Controller khác/webhook ghi thêm field (vd replicas do HPA) Dùng ignoreDifferences trong Application, hoặc bỏ replicas khỏi manifest khi dùng HPA
ComparisonError / rpc error khi render Lỗi YAML/Helm/Kustomize trong repo, hoặc không truy cập được repo argocd app get web xem message; thử helm template/kustomize build cục bộ
Application bị xoá nhưng resource vẫn còn (hoặc ngược lại) Có/không có finalizer resources-finalizer Thêm hoặc bỏ finalizer đúng ý định
argocd app rollback báo lỗi auto-sync Auto-sync đang bật argocd app set web --sync-policy none rồi rollback
Sync fail vì CRD chưa có Resource dùng CRD cùng lượt sync Cài CRD trước (app riêng), hoặc dùng sync wave annotation
Thay đổi trong Git không thấy ngay Mặc định poll theo chu kỳ, không tức thì Cấu hình webhook từ Git, hoặc argocd app get web --refresh

Tham khảo