GitOps đổi câu hỏi từ "làm sao đẩy thay đổi lên cluster" sang
"làm sao giữ cluster luôn khớp với Git". Khác biệt nghe nhỏ nhưng thay đổi mọi thứ: rollback thành
git revert, audit thành git log, và không ai cần credential ghi vào production.
Mười mục: nguyên lý GitOps (1) → kiến trúc ArgoCD (2) → Application (3) → App of Apps và ApplicationSet (4) → sync policy (5) → sync wave và hook (6) → rollback và khôi phục (7) → nhiều môi trường (8) → bảo mật (9) → checklist (10).
| Push (CI tự deploy) | Pull (GitOps) | |
|---|---|---|
| Ai khởi động | CI gọi kubectl/helm vào cluster |
Agent trong cluster tự kéo từ Git |
| Credential | CI phải giữ credential ghi vào production | CI chỉ cần quyền ghi một repo Git. Không credential cluster nào ra ngoài. |
| Mạng | CI phải tới được API server (thường phải mở đường vào VPC) | Chỉ cần cluster ra được Git. API server có thể hoàn toàn private. |
| Sai lệch thủ công | Không phát hiện. Ai sửa bằng kubectl thì nó
tồn tại tới lần deploy sau. |
Phát hiện trong vài giây và tự kéo về nếu bật self-heal. |
| Rollback | Chạy lại job cũ — mà job cũ có thể không còn tái lập được | git revert. Luôn tái lập được. |
| Audit | Log CI, bị xoá theo retention | git log — vĩnh viễn, có review, có người phê duyệt |
| Dựng lại cluster | Chạy lại hàng chục job theo đúng thứ tự | Trỏ agent vào repo, cluster tự dựng lại |
┌──────────────────────────────────────────┐
│ │
▼ │
1. Đọc Git (mỗi 3 phút, hoặc ngay khi có webhook) │
│ │
▼ │
2. Render manifest (helm template / kustomize) │
│ │
▼ │
3. So với trạng thái THẬT trong cluster │
│ │
├── Khớp → Synced, không làm gì ────────┤
│ │
└── Lệch → OutOfSync │
│ │
├── automated: tự apply ──────────┤
└── manual: chờ người bấm ────────┘
| Trạng thái | Nghĩa là gì | Ví dụ dễ nhầm |
|---|---|---|
Sync statusSynced / OutOfSync |
Manifest trong cluster có khớp với Git hay không | Synced nhưng mọi pod CrashLoopBackOff: manifest đúng y như Git, chỉ
là ứng dụng lỗi. |
Health statusHealthy / Degraded / Progressing |
Tài nguyên có đang hoạt động tốt hay không | Healthy nhưng OutOfSync: app chạy tốt, nhưng ai đó vừa commit thay
đổi chưa được sync. |
Synced + Healthy. Mọi tổ hợp khác đều
cần xem:
OutOfSync + Healthy → có thay đổi chờ sync, hoặc có sai lệch thủ côngSynced + Degraded → manifest đúng nhưng app lỗi. Vấn đề ở ứng
dụng, không ở GitOps. Quay lại chặng 04, mục 9.Synced + Progressing kéo dài → rollout bị kẹt, thường do probe fail
hoặc không đủ tài nguyên để xếp pod mới| Nằm trong Git | KHÔNG nằm trong Git |
|---|---|
|
|
Synced nhưng mọi pod CrashLoopBackOff. Nghĩa là gì?| Thành phần | Làm gì | Khi nào cần chú ý |
|---|---|---|
application-controller |
Vòng lặp điều chỉnh: so Git với cluster, áp dụng thay đổi | Nhiều Application thì đây là nút cổ chai. Tăng
--status-processors và --operation-processors. |
repo-server |
Clone Git, render Helm/Kustomize thành manifest | Chart lớn hoặc nhiều app thì tốn CPU và RAM ở đây. Scale thêm replica. |
api-server |
API và giao diện web, xử lý xác thực | Nơi cấu hình SSO và RBAC. |
redis |
Cache manifest đã render và trạng thái | Mất Redis thì ArgoCD chậm hẳn nhưng không mất dữ liệu — cache tự dựng lại. |
applicationset-controller |
Sinh Application từ generator | Dùng khi có nhiều service cùng khuôn. |
notifications-controller |
Gửi thông báo khi sync thành công hoặc thất bại | Nên bật — xem mục 7. |
global:
domain: argocd.internal.example.com
configs:
params:
# TLS do ALB xử lý, ArgoCD chạy HTTP phía sau
server.insecure: true
# Tăng số luồng xử lý khi có nhiều Application
controller.status.processors: "20"
controller.operation.processors: "10"
# Giới hạn tốc độ gọi API server để không làm quá tải control plane
controller.kubectl.parallelism.limit: "10"
cm:
# Chu kỳ đọc Git khi KHÔNG có webhook. Dùng webhook thì để dài.
timeout.reconciliation: 180s
# Bỏ qua khác biệt do controller khác quản lý — xem mục 5
resource.customizations.ignoreDifferences.apps_Deployment: |
jsonPointers:
- /spec/replicas
# Đánh dấu Secret do ESO tạo là "không cần so sánh"
resource.exclusions: |
- apiGroups: ["external-secrets.io"]
kinds: ["ExternalSecret"]
clusters: []
rbac:
policy.default: role:readonly
policy.csv: |
p, role:dev, applications, get, */*, allow
p, role:dev, applications, sync, dev/*, allow
p, role:dev, logs, get, */*, allow
p, role:platform, applications, *, */*, allow
p, role:platform, clusters, *, *, allow
g, myorg:platform-team, role:platform
g, myorg:developers, role:dev
# Repo và credential khai báo trước, không thêm tay qua giao diện
repositories:
gitops-config:
url: https://github.com/myorg/gitops-config.git
type: git
name: gitops-config
platform-charts:
url: https://github.com/myorg/platform-charts.git
type: git
name: platform-charts
controller:
replicas: 1 # controller KHÔNG scale ngang được, chỉ scale dọc
resources:
requests: { cpu: 500m, memory: 1Gi }
limits: { cpu: 2000m, memory: 4Gi }
repoServer:
replicas: 3 # scale ngang được, scale theo số app và độ lớn chart
resources:
requests: { cpu: 250m, memory: 512Mi }
limits: { cpu: 1000m, memory: 2Gi }
server:
replicas: 2
ingress:
enabled: true
ingressClassName: alb
annotations:
alb.ingress.kubernetes.io/scheme: internal # KHÔNG phơi ra internet
alb.ingress.kubernetes.io/target-type: ip
alb.ingress.kubernetes.io/certificate-arn: arn:aws:acm:ap-southeast-1:123456789012:certificate/abc
alb.ingress.kubernetes.io/listen-ports: '[{"HTTPS":443}]'
hostname: argocd.internal.example.com
applicationSet:
replicas: 2
notifications:
enabled: true
dex:
enabled: false # dùng OIDC trực tiếp thay vì Dex nếu IdP hỗ trợ
helm repo add argo https://argoproj.github.io/argo-helm
helm upgrade --install argocd argo/argo-cd \
-n argocd --create-namespace \
-f argocd-values.yaml \
--version 7.7.11
# Lấy mật khẩu admin ban đầu (đổi ngay sau khi vào được)
kubectl -n argocd get secret argocd-initial-admin-secret \
-o jsonpath='{.data.password}' | base64 -d
# Sau khi cấu hình SSO: TẮT tài khoản admin
kubectl -n argocd patch cm argocd-cm --type merge \
-p '{"data":{"admin.enabled":"false"}}'
scheme: internal, truy cập qua VPN.admin sau khi cấu hình SSO. Dùng OIDC với MFA.policy.default: role:readonly. Mặc định của ArgoCD khá
rộng.# Tạo secret cho webhook
kubectl -n argocd create secret generic argocd-secret \
--from-literal=webhook.github.secret="$(openssl rand -hex 20)" \
--dry-run=client -o yaml | kubectl apply -f -
# Trong GitHub repo settings → Webhooks:
# Payload URL: https://argocd.internal.example.com/api/webhook
# Content type: application/json
# Secret: giá trị vừa tạo
# Events: Just the push event
Không có webhook, ArgoCD chỉ đọc Git theo timeout.reconciliation (mặc định
3 phút). Có webhook thì sync gần như tức thì. Nếu ArgoCD nằm trong VPC kín không nhận được webhook từ
internet, giảm timeout.reconciliation xuống 60s — nhưng chú ý nó làm tăng tải lên
repo-server.
# Đăng nhập
argocd login argocd.internal.example.com --sso
# Xem và theo dõi
argocd app list
argocd app list -o wide --selector env=prod
argocd app get order-service-prod
argocd app get order-service-prod --refresh # buộc đọc lại Git ngay
# Xem khác biệt giữa Git và cluster — LỆNH QUAN TRỌNG NHẤT
argocd app diff order-service-prod
# Sync
argocd app sync order-service-prod
argocd app sync order-service-prod --dry-run
argocd app sync order-service-prod --prune # xoá tài nguyên không còn trong Git
argocd app sync order-service-prod --resource apps:Deployment:order-service
argocd app wait order-service-prod --health --timeout 600
# Lịch sử và rollback
argocd app history order-service-prod
argocd app rollback order-service-prod 42
# Debug
argocd app manifests order-service-prod # manifest ArgoCD đã render
argocd app logs order-service-prod --follow
argocd app resources order-service-prod
argocd app diff là lệnh dùng nhiều nhất. Nó cho thấy chính xác field nào lệch giữa
Git và cluster — trả lời ngay câu hỏi "vì sao app này OutOfSync". Nếu diff hiện những
field bạn không quản lý (ví dụ replicas do HPA đổi), đó là dấu hiệu cần cấu hình
ignoreDifferences — xem mục 5.
Một Application trả lời ba câu hỏi: manifest ở đâu (source),
áp vào đâu (destination), áp thế nào (syncPolicy).
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: order-service-prod
namespace: argocd
labels:
env: prod
team: payments
# Finalizer: khi xoá Application thì xoá luôn tài nguyên nó tạo.
# KHÔNG có finalizer này thì xoá Application sẽ để lại pod chạy mồ côi.
finalizers:
- resources-finalizer.argocd.argoproj.io
spec:
project: prod
source:
repoURL: https://github.com/myorg/gitops-config.git
targetRevision: main
path: apps/order-service
helm:
valueFiles:
- base.yaml
- prod.yaml
# Giá trị ghi trực tiếp — ưu tiên cao hơn valueFiles.
# Hạn chế dùng: nó làm Git không còn là nguồn sự thật đầy đủ.
parameters:
- name: global.environment
value: production
destination:
server: https://kubernetes.default.svc
namespace: prod
syncPolicy:
automated:
prune: true # xoá tài nguyên đã bị bỏ khỏi Git
selfHeal: true # kéo về đúng Git khi có sai lệch thủ công
allowEmpty: false # KHÔNG cho sync nếu render ra rỗng (chống xoá sạch do lỗi chart)
syncOptions:
- CreateNamespace=false # namespace do app riêng quản lý
- PrunePropagationPolicy=foreground
- PruneLast=true # xoá tài nguyên cũ SAU khi cái mới đã khoẻ
- ServerSideApply=true # tránh lỗi annotation quá lớn với CRD
- RespectIgnoreDifferences=true
retry:
limit: 5
backoff:
duration: 5s
factor: 2
maxDuration: 3m
# Bỏ qua field do controller khác quản lý
ignoreDifferences:
- group: apps
kind: Deployment
jsonPointers:
- /spec/replicas # HPA/KEDA điều khiển
revisionHistoryLimit: 10
Đây là mô hình thực tế khi dùng generic chart (xem chặng 05, mục 7): chart dùng chung nằm ở repo riêng, values của từng service nằm ở repo cấu hình.
spec:
sources:
# Nguồn 1: chart dùng chung, ghim theo tag
- repoURL: https://github.com/myorg/platform-charts.git
targetRevision: v1.4.0
path: charts/generic-service
helm:
valueFiles:
# $values trỏ tới source có ref: values bên dưới
- $values/apps/order-service/base.yaml
- $values/apps/order-service/prod.yaml
# Nguồn 2: repo values, chỉ để tham chiếu (không render gì)
- repoURL: https://github.com/myorg/gitops-config.git
targetRevision: main
ref: values
targetRevision ở một chỗ, áp
cho mọi service. Và CI chỉ cần quyền ghi vào repo values, không cần quyền với repo chart — giảm bề mặt
rủi ro.
AppProject là cơ chế phân quyền và giới hạn. Đừng dùng project
default cho production — nó cho phép mọi thứ.
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
name: prod
namespace: argocd
spec:
description: Production workloads
# Chỉ cho phép manifest từ những repo này
sourceRepos:
- https://github.com/myorg/gitops-config.git
- https://github.com/myorg/platform-charts.git
# Chỉ cho phép deploy vào những namespace này
destinations:
- server: https://kubernetes.default.svc
namespace: prod
- server: https://kubernetes.default.svc
namespace: prod-jobs
# Chặn việc tạo tài nguyên ở cấp cluster — trừ những loại cho phép
clusterResourceWhitelist:
- group: ""
kind: Namespace
# Chặn tường minh những thứ nguy hiểm
namespaceResourceBlacklist:
- group: ""
kind: ResourceQuota
- group: rbac.authorization.k8s.io
kind: ClusterRole
- group: rbac.authorization.k8s.io
kind: ClusterRoleBinding
# Cửa sổ thời gian được phép sync — chặn deploy ngoài giờ làm việc
syncWindows:
- kind: allow
schedule: "0 8 * * 1-5" # cho phép từ 8h
duration: 10h # tới 18h, thứ 2 tới thứ 6
applications: ["*"]
manualSync: true # vẫn cho sync tay khi cần xử lý sự cố
- kind: deny
schedule: "0 0 * * 6,0" # chặn cuối tuần
duration: 24h
applications: ["*"]
manualSync: true
roles:
- name: developer
description: Xem và sync, không sửa được Application
policies:
- p, proj:prod:developer, applications, get, prod/*, allow
- p, proj:prod:developer, applications, sync, prod/*, allow
- p, proj:prod:developer, logs, get, prod/*, allow
groups:
- myorg:developers
syncWindows giải quyết một vấn đề thật: với automated.selfHeal, một
commit vào Git lúc 11 giờ đêm sẽ được deploy ngay. syncWindows giới hạn việc sync tự động
vào giờ làm việc, nhưng vẫn cho manualSync để bạn xử lý được sự cố ngoài giờ.
ArgoCD biết cách đánh giá sức khoẻ của Deployment, Service, Ingress. Với CRD của bên thứ
ba (ví dụ ScaledObject của KEDA), nó không biết nên mặc định coi là
Healthy — che mất vấn đề.
data:
resource.customizations.health.external-secrets.io_ExternalSecret: |
hs = {}
if obj.status ~= nil and obj.status.conditions ~= nil then
for i, condition in ipairs(obj.status.conditions) do
if condition.type == "Ready" then
if condition.status == "True" then
hs.status = "Healthy"
hs.message = condition.message
return hs
else
hs.status = "Degraded"
hs.message = condition.message
return hs
end
end
end
end
hs.status = "Progressing"
hs.message = "Đang chờ ExternalSecret đồng bộ"
return hs
Không có health check này, một ExternalSecret không đọc được secret (sai
IAM, secret không tồn tại) vẫn hiện Healthy — và bạn chỉ phát hiện khi pod không khởi động
được vì thiếu biến môi trường.
finalizers. Chuyện gì xảy ra?Viết tay 40 Application là không khả thi. Hai mô hình giải quyết: App of Apps (một app quản lý các app khác) và ApplicationSet (sinh app từ generator).
gitops-config/
├── bootstrap/
│ └── root.yaml ← Application DUY NHẤT bạn tạo bằng tay
├── infrastructure/ ← hạ tầng, sync trước ứng dụng
│ ├── 00-namespaces.yaml
│ ├── 10-external-secrets.yaml
│ ├── 20-aws-lb-controller.yaml
│ ├── 30-keda.yaml
│ ├── 40-prometheus-stack.yaml
│ └── 50-cert-manager.yaml
└── apps/ ← ứng dụng
├── order-service/
├── payment-service/
└── report-worker/
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: root
namespace: argocd
finalizers:
- resources-finalizer.argocd.argoproj.io
spec:
project: platform
source:
repoURL: https://github.com/myorg/gitops-config.git
targetRevision: main
path: infrastructure # thư mục chứa các Application khác
directory:
recurse: true
destination:
server: https://kubernetes.default.svc
namespace: argocd
syncPolicy:
automated:
prune: true
selfHeal: true
allowEmpty: false
kubectl apply -f bootstrap/root.yaml. ArgoCD tự tạo mọi Application còn lại, chúng tự tạo
mọi tài nguyên. Đây là lợi ích cụ thể và kiểm chứng được của GitOps — và bạn nên thử trên một
cluster nháp để biết nó thực sự hoạt động.
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: external-secrets
namespace: argocd
annotations:
# Số nhỏ sync trước. ESO phải có trước khi app cần secret.
argocd.argoproj.io/sync-wave: "10"
finalizers:
- resources-finalizer.argocd.argoproj.io
spec:
project: platform
source:
repoURL: https://charts.external-secrets.io
chart: external-secrets
targetRevision: 0.10.5
helm:
values: |
installCRDs: true
serviceAccount:
annotations:
eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/eso-secrets-reader
destination:
server: https://kubernetes.default.svc
namespace: external-secrets
syncPolicy:
automated: { prune: true, selfHeal: true, allowEmpty: false }
syncOptions:
- CreateNamespace=true
- ServerSideApply=true
| Wave | Thành phần | Vì sao thứ tự này |
|---|---|---|
0 | Namespace, ResourceQuota, LimitRange | Mọi thứ khác cần namespace tồn tại trước. |
10 | External Secrets Operator, cert-manager | App cần secret và certificate. |
20 | AWS Load Balancer Controller, CNI config | Ingress cần controller này để tạo ALB. |
30 | KEDA, metrics-server | ScaledObject của app cần KEDA CRD. |
40 | Prometheus stack, Loki | ServiceMonitor của app cần CRD của Prometheus Operator. |
100 | Ứng dụng | Sau khi mọi thứ chúng phụ thuộc đã sẵn sàng. |
Ba generator dùng nhiều nhất: git directory (quét thư mục), matrix (tổ hợp nhiều generator), và cluster (nhiều cluster).
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
name: prod-services
namespace: argocd
spec:
# Khi Application do set này sinh ra bị xoá khỏi generator, xoá luôn tài nguyên
syncPolicy:
preserveResourcesOnDeletion: false
generators:
- git:
repoURL: https://github.com/myorg/gitops-config.git
revision: main
directories:
- path: apps/*
# Loại trừ service chưa sẵn sàng cho prod
- path: apps/experimental-*
exclude: true
template:
metadata:
name: '{{.path.basename}}-prod'
labels:
env: prod
finalizers:
- resources-finalizer.argocd.argoproj.io
spec:
project: prod
sources:
- repoURL: https://github.com/myorg/platform-charts.git
targetRevision: v1.4.0
path: charts/generic-service
helm:
valueFiles:
- $values/{{.path.path}}/base.yaml
- $values/{{.path.path}}/prod.yaml
- repoURL: https://github.com/myorg/gitops-config.git
targetRevision: main
ref: values
destination:
server: https://kubernetes.default.svc
namespace: prod
syncPolicy:
automated: { prune: true, selfHeal: true, allowEmpty: false }
syncOptions:
- PruneLast=true
- ServerSideApply=true
spec:
generators:
- matrix:
generators:
# Generator 1: danh sách service từ thư mục
- git:
repoURL: https://github.com/myorg/gitops-config.git
revision: main
directories:
- path: apps/*
# Generator 2: danh sách môi trường
- list:
elements:
- env: dev
namespace: dev
chartVersion: v1.4.0
autoSync: "true"
- env: staging
namespace: staging
chartVersion: v1.4.0
autoSync: "true"
- env: prod
namespace: prod
chartVersion: v1.4.0
autoSync: "false" # prod sync tay
template:
metadata:
name: '{{.path.basename}}-{{.env}}'
spec:
project: '{{.env}}'
sources:
- repoURL: https://github.com/myorg/platform-charts.git
targetRevision: '{{.chartVersion}}'
path: charts/generic-service
helm:
valueFiles:
- $values/{{.path.path}}/base.yaml
- $values/{{.path.path}}/{{.env}}.yaml
- repoURL: https://github.com/myorg/gitops-config.git
targetRevision: main
ref: values
destination:
server: https://kubernetes.default.svc
namespace: '{{.namespace}}'
Matrix sinh ra số service × số môi trường Application. Với 20 service và 3 môi
trường là 60 Application từ một file — và thêm service mới chỉ cần tạo thư mục trong
apps/.
applicationsetcontroller.enable.progressive.syncs và dùng
strategy: RollingSync để thay đổi lan dần theo nhóm, không áp đồng loạt.preserveResourcesOnDeletion: true ở môi trường production — nếu Application
bị xoá do lỗi generator, tài nguyên vẫn giữ lại, pod vẫn chạy.allowEmpty: false — chặn trường hợp generator trả rỗng và ArgoCD xoá
sạch.spec:
strategy:
type: RollingSync
rollingSync:
steps:
- matchExpressions:
- key: env
operator: In
values: [dev]
- matchExpressions:
- key: env
operator: In
values: [staging]
- matchExpressions:
- key: env
operator: In
values: [prod]
maxUpdate: 1 # prod: mỗi lần chỉ một app
Mỗi bước chờ bước trước Healthy mới tiếp tục. Thay đổi chart version sẽ đi
dev → staging → prod, và ở prod thì từng app một. Nếu một app lỗi, chuỗi dừng lại.
allowEmpty: false quan trọng khi bật prune: true?| Cấu hình | Hành vi | Dùng cho |
|---|---|---|
Không có automated |
ArgoCD chỉ báo OutOfSync. Người bấm sync. |
Production ở tổ chức cần kiểm soát từng lần deploy. |
automated + prune: false + selfHeal: false |
Tự áp dụng khi Git đổi. Nhưng không xoá tài nguyên đã bỏ khỏi Git, và không sửa sai lệch thủ công. | Bước chuyển tiếp khi mới áp GitOps — ít rủi ro nhất. |
automated + prune: true + selfHeal: true |
GitOps đầy đủ. Git là nguồn sự thật duy nhất; mọi sai lệch bị kéo về. | Mục tiêu nên hướng tới. Bắt đầu ở dev, rồi staging, rồi prod. |
selfHeal — điều gì thực sự xảy ra# Ai đó sửa tay:
kubectl scale deploy/order-service --replicas=10 -n prod
# Với selfHeal: false
# → ArgoCD báo OutOfSync, hiện diff, nhưng GIỮ NGUYÊN 10 replica
# → Thay đổi tồn tại tới lần sync tiếp theo
# Với selfHeal: true
# → ArgoCD phát hiện trong vài giây và đưa về giá trị trong Git
# → Thay đổi thủ công BỊ MẤT
selfHeal: true nghĩa là kubectl edit không còn là cách sửa hệ thống.
Đây là điều cả đội phải hiểu và đồng ý trước khi bật. Với một đội mới chuyển sang GitOps, việc thay đổi
bị hoàn tác sau 30 giây gây bối rối — nên hãy truyền đạt rõ trước khi bật, và bật ở dev trước.
ignoreDifferences — xử lý field do controller khác quản lýspec.replicas của Deployment. ArgoCD thấy giá trị
thật (7) khác Git (3) nên coi là sai lệch và kéo về 3. HPA lại tăng lên 7. Hai bên đẩy nhau vô
hạn — pod bị tạo rồi xoá liên tục.
# Cách sửa 1: bỏ qua field replicas
ignoreDifferences:
- group: apps
kind: Deployment
jsonPointers:
- /spec/replicas
# Cách sửa 2 (tốt hơn): KHÔNG render replicas khi autoscaling bật
# Trong Helm template — xem chặng 05 mục 3
{{- if not (or .Values.autoscaling.enabled .Values.autoscaling.keda.enabled) }}
replicas: {{ .Values.replicaCount }}
{{- end }}
Cách 2 tốt hơn vì nó làm Git phản ánh đúng sự thật: "số replica không do Git quyết định".
Cách 1 chỉ che vấn đề đi.
ignoreDifferencesignoreDifferences:
# HPA/KEDA điều khiển số replica
- group: apps
kind: Deployment
jsonPointers:
- /spec/replicas
# Webhook injection: service mesh, vault agent tiêm sidecar vào pod
- group: apps
kind: Deployment
jqPathExpressions:
- '.spec.template.spec.containers[] | select(.name == "istio-proxy")'
# CRD lớn: field status và caBundle do controller ghi
- group: apiextensions.k8s.io
kind: CustomResourceDefinition
jqPathExpressions:
- '.spec.conversion.webhook.clientConfig.caBundle'
- '.status'
# Secret do External Secrets Operator tạo — ArgoCD không quản lý nội dung
- group: ""
kind: Secret
name: order-service
jsonPointers:
- /data
# ServiceAccount token tự sinh
- group: ""
kind: ServiceAccount
jsonPointers:
- /secrets
# Bỏ qua mọi field do controller khác thay đổi (Kubernetes 1.18+)
- group: apps
kind: Deployment
managedFieldsManagers:
- kube-controller-manager
syncOptions — các tuỳ chọn đáng biết| Option | Làm gì và khi nào cần |
|---|---|
ServerSideApply=true |
Dùng server-side apply thay vì client-side. Cần cho CRD lớn (Prometheus Operator,
Istio) vì client-side apply lưu toàn bộ manifest vào annotation
last-applied-configuration và vượt giới hạn 256 KB. |
PruneLast=true |
Xoá tài nguyên cũ sau khi tài nguyên mới đã khoẻ. Giảm khoảng thời gian không có gì phục vụ. Nên bật. |
PrunePropagationPolicy=foreground |
Chờ tài nguyên con bị xoá xong mới xoá cha. Tránh để lại ReplicaSet mồ côi. |
CreateNamespace=true |
Tự tạo namespace nếu chưa có. Tiện cho hạ tầng, nhưng với app thì nên để namespace do một Application riêng quản lý (để có label Pod Security và ResourceQuota). |
Replace=true |
Dùng kubectl replace thay vì apply. Cẩn thận: nó xoá rồi tạo
lại, gây downtime. Chỉ dùng cho tài nguyên có field bất biến đang bị kẹt. |
ApplyOutOfSyncOnly=true |
Chỉ áp dụng tài nguyên đang lệch, bỏ qua cái đã khớp. Giảm tải API server khi app có nhiều tài nguyên. |
RespectIgnoreDifferences=true |
Áp dụng ignoreDifferences cả lúc sync, không chỉ lúc so sánh. Thường cần
cùng với ignoreDifferences — thiếu nó thì sync vẫn ghi đè field bạn muốn bỏ qua. |
syncPolicy:
automated:
prune: true
selfHeal: true
allowEmpty: false
syncOptions:
- CreateNamespace=true
Tự động hoàn toàn. CI bump tag là deploy ngay. Hỏng thì sửa Git, không ai bị ảnh hưởng.
syncPolicy:
automated:
prune: true
selfHeal: true
allowEmpty: false
syncOptions:
- PruneLast=true
- ServerSideApply=true
retry:
limit: 3
Tự động, nhưng cấu hình giống prod để phát hiện vấn đề trước khi lên prod.
syncPolicy:
automated:
prune: true
selfHeal: true
allowEmpty: false
syncOptions:
- PruneLast=true
- ServerSideApply=true
- RespectIgnoreDifferences=true
retry:
limit: 5
backoff:
duration: 5s
factor: 2
maxDuration: 3m
Vẫn tự động — nhưng cổng kiểm soát nằm ở pull request
của repo cấu hình, cộng syncWindows của AppProject.
OutOfSync, và dần dần không ai
biết trạng thái OutOfSync nào là cố ý, cái nào là sai lệch thật. Mất luôn giá trị của việc
phát hiện sai lệch.
ignoreDifferences cho /spec/replicas nhưng sync vẫn đưa replicas về giá trị Git. Thiếu gì?ArgoCD áp dụng tài nguyên theo thứ tự mặc định hợp lý (Namespace trước, CRD trước CR…). Khi cần thứ tự riêng — ví dụ migration database trước khi pod mới lên — bạn dùng wave và hook.
# Annotation trên từng tài nguyên. Số nhỏ áp dụng trước.
# Mặc định là 0. Số âm chạy trước mặc định.
metadata:
annotations:
argocd.argoproj.io/sync-wave: "-5"
Healthy mới sang wave tiếp theo. Đây là
khác biệt quan trọng so với kubectl apply — nó cho phép diễn đạt phụ thuộc thật.
| Wave | Tài nguyên | Vì sao |
|---|---|---|
-10 | ServiceAccount, ExternalSecret | Pod cần secret tồn tại trước khi khởi động. |
-5 | Job migration (PreSync hook) | Schema phải sẵn sàng trước khi code mới chạy. |
0 | ConfigMap, Secret, Deployment, Service | Mặc định. |
5 | Ingress, ServiceMonitor | Chỉ có nghĩa khi Service đã tồn tại. |
10 | HPA, ScaledObject, PDB | Cần Deployment tồn tại để tham chiếu. |
| Hook | Chạy khi nào |
|---|---|
PreSync | Trước khi áp dụng manifest. Dùng cho migration database. |
Sync | Cùng lúc với manifest, theo wave. |
PostSync | Sau khi mọi tài nguyên Healthy. Dùng cho smoke test, cache warming. |
SyncFail | Khi sync thất bại. Dùng để thông báo hoặc dọn dẹp. |
PostDelete | Sau khi Application bị xoá. Dọn tài nguyên ngoài cluster. |
{{- if .Values.migration.enabled }}
apiVersion: batch/v1
kind: Job
metadata:
name: {{ include "app.fullname" . }}-migration
annotations:
# --- Dành cho ArgoCD ---
argocd.argoproj.io/hook: PreSync
argocd.argoproj.io/hook-delete-policy: BeforeHookCreation
argocd.argoproj.io/sync-wave: "-5"
# --- Dành cho Helm (khi deploy bằng helm upgrade) ---
"helm.sh/hook": pre-install,pre-upgrade
"helm.sh/hook-weight": "-5"
"helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded
spec:
backoffLimit: 2
activeDeadlineSeconds: 600 # cắt sau 10 phút, không treo sync vô hạn
ttlSecondsAfterFinished: 86400 # giữ 1 ngày để đọc log
template:
spec:
restartPolicy: Never
serviceAccountName: {{ include "app.serviceAccountName" . }}
containers:
- name: migration
# CÙNG image với app — đảm bảo schema khớp code
image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
command: {{ toYaml .Values.migration.command | nindent 12 }}
envFrom:
- configMapRef: { name: {{ include "app.fullname" . }} }
- secretRef: { name: {{ include "app.fullname" . }} }
{{- end }}
hook-delete-policy của ArgoCD:
BeforeHookCreation |
Xoá hook cũ trước khi tạo mới. Cần có — Job có field bất biến nên không apply lại được. |
HookSucceeded |
Xoá sau khi thành công. Sạch, nhưng mất log ngay cả khi thành công. |
HookFailed |
Xoá cả khi thất bại. Đừng dùng — bạn sẽ mất log của migration lỗi. |
BeforeHookCreation, cộng
ttlSecondsAfterFinished trên Job để Kubernetes tự dọn sau một ngày. Như vậy bạn luôn có
log của lần migration gần nhất.
apiVersion: batch/v1
kind: Job
metadata:
name: {{ include "app.fullname" . }}-smoke-test
annotations:
argocd.argoproj.io/hook: PostSync
argocd.argoproj.io/hook-delete-policy: BeforeHookCreation
spec:
backoffLimit: 1
activeDeadlineSeconds: 180
ttlSecondsAfterFinished: 3600
template:
spec:
restartPolicy: Never
containers:
- name: smoke
image: curlimages/curl:latest
command:
- sh
- -c
- |
set -e
SVC="http://{{ include "app.fullname" . }}:{{ .Values.service.port }}"
echo "1. Readiness..."
curl -fsS --max-time 10 "$SVC{{ .Values.probes.readiness.path }}"
echo "2. Metrics có số liệu..."
curl -fsS --max-time 10 "$SVC{{ .Values.serviceMonitor.path }}" \
| grep -q 'jvm_memory_used_bytes\|process_cpu_seconds_total'
echo "3. Endpoint nghiệp vụ trả 200..."
code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 10 "$SVC/api/v1/health")
[ "$code" = "200" ] || { echo "nhận $code, mong đợi 200"; exit 1; }
echo "Smoke test OK"
Degraded — và nếu bạn đã cấu hình
notification, cả đội biết ngay. Đây là cách rẻ nhất để phát hiện deploy hỏng mà không cần hệ thống
kiểm thử riêng.
# 1. Xem Job nào thất bại
kubectl get jobs -n prod -l app.kubernetes.io/instance=order-service-prod
argocd app get order-service-prod
# 2. Đọc log của Job thất bại
kubectl logs -n prod job/order-service-migration
# 3. Sau khi sửa Git, sync lại. ArgoCD xoá Job cũ (BeforeHookCreation) và chạy lại.
argocd app sync order-service-prod
# 4. Nếu cần bỏ qua hook để xử lý sự cố gấp
argocd app sync order-service-prod --strategy=apply --force
# CẨN THẬN: bỏ qua migration có thể làm code mới chạy trên schema cũ
# 5. Xoá Job kẹt bằng tay
kubectl delete job -n prod order-service-migration
1. PreSync hook (wave -5) → Job migration, chờ Complete
↓ thất bại → DỪNG, manifest KHÔNG được áp dụng
2. Wave -10 → ServiceAccount, ExternalSecret
↓ chờ Healthy
3. Wave 0 → ConfigMap, Secret, Deployment, Service
↓ chờ Deployment Healthy (pod Ready)
4. Wave 5 → Ingress, ServiceMonitor
↓
5. Wave 10 → HPA, ScaledObject, PDB
↓
6. PostSync hook → smoke test
↓ thất bại → Application Degraded
7. Prune (nếu PruneLast=true) → xoá tài nguyên không còn trong Git
argocd.argoproj.io/hook: PreSync và thất bại. Deployment có được cập nhật không?Với GitOps, rollback có hai dạng: revert trong Git (đúng chuẩn, để lại dấu vết) và
argocd app rollback (nhanh, nhưng tạo sai lệch với Git). Biết dùng cái nào khi nào là
điểm quan trọng.
| Cách | Làm gì | Đánh đổi |
|---|---|---|
git revertkhuyến nghị |
Tạo commit mới hoàn tác commit cũ, ArgoCD sync như bình thường. | Giữ nguyên nguyên lý GitOps. Git vẫn là nguồn sự thật, có dấu vết ai revert và vì sao. Chậm hơn vài chục giây vì phải qua Git. |
argocd app rollback |
Áp lại manifest của một revision cũ trực tiếp vào cluster. | Nhanh nhất (vài giây). Nhưng cluster lệch với Git ngay lập tức. Nếu self-heal đang bật, ArgoCD sẽ kéo về lại bản trong Git — tức rollback bị hoàn tác. Phải tắt auto-sync trước. |
Sửa image.tag về giá trị cũ |
Commit một thay đổi trỏ lại ảnh trước đó. | Rõ ràng và dễ hiểu khi chỉ cần quay lui phiên bản ảnh. Nhưng không hoàn tác được các thay đổi khác đi kèm trong cùng commit. |
argocd app rollback với auto-sync đang bật. Rollback áp manifest cũ vào
cluster, nhưng Git vẫn chứa phiên bản mới. Vòng lặp điều chỉnh tiếp theo thấy sai lệch và kéo về lại
phiên bản mới — tức là sự cố quay lại sau vài chục giây, trong khi bạn tưởng đã xử lý xong.
# Thứ tự ĐÚNG khi cần rollback khẩn cấp bằng ArgoCD:
argocd app set order-service-prod --sync-policy none # 1. TẮT auto-sync trước
argocd app rollback order-service-prod 42 # 2. rollback
# 3. Sửa Git cho khớp (revert commit gây lỗi)
# 4. Bật lại auto-sync
argocd app set order-service-prod --sync-policy automated --self-heal
# ---------- Trường hợp 1: vừa deploy xong và thấy lỗi ngay ----------
# Nhanh nhất mà vẫn đúng chuẩn: revert commit bump tag trong repo GitOps
cd gitops-config
git log --oneline -5 apps/order-service/prod.yaml
git revert --no-edit <sha-của-commit-bump>
git push
# ArgoCD sync trong vài giây nếu có webhook. Theo dõi:
argocd app wait order-service-prod --health --timeout 300
# ---------- Trường hợp 2: không biết commit nào gây lỗi ----------
argocd app history order-service-prod
# ID DATE REVISION
# 41 2026-11-05 09:12:00 main (3f8a1c2)
# 42 2026-11-05 14:30:00 main (a3f8c21) ← bản đang lỗi
argocd app diff order-service-prod --revision 3f8a1c2
# ^ xem bản cũ khác bản hiện tại ở đâu
# ---------- Trường hợp 3: cần dừng chảy máu NGAY (dưới 10 giây) ----------
# Scale về 0 rồi điều tra sau — chỉ dùng khi lỗi đang gây thiệt hại thật
argocd app set order-service-prod --sync-policy none
kubectl scale deploy order-service -n prod --replicas=0
# Hoặc quay lại ReplicaSet cũ (bỏ qua ArgoCD hoàn toàn)
kubectl rollout undo deploy/order-service -n prod
# LƯU Ý: cả hai cách này tạo sai lệch với Git. PHẢI sửa Git ngay sau đó.
git revert tốt hơn git reset: revert tạo commit
mới nên lịch sử được giữ nguyên — người sau đọc git log thấy được "đã deploy rồi đã quay
lui vì lý do này". reset --hard và force push xoá lịch sử, làm mất chính thứ khiến GitOps
có giá trị, và gây xung đột cho mọi người đang làm việc trên repo đó.
| Thứ không rollback được | Phải xử lý thế nào |
|---|---|
| Schema database đã migrate | Migration đã chạy thì đã chạy. Đây là lý do mọi migration phải tương thích ngược: tách thành nhiều lần deploy (thêm cột → ghi cả hai → bỏ cột cũ). Xem chặng 05, mục 6. |
| Message đã gửi vào queue | Consumer phiên bản cũ phải xử lý được message do phiên bản mới sinh ra. Đánh version cho message schema. |
| Dữ liệu đã ghi với định dạng mới | Code cũ phải đọc được định dạng mới, hoặc cần script chuyển đổi ngược — và script đó phải được viết trước khi deploy. |
| Email, thông báo, webhook đã gửi ra ngoài | Không hoàn tác được. Chỉ giảm thiểu bằng canary hoặc feature flag. |
| Tài nguyên AWS do Crossplane/ACK tạo | Revert có thể xoá tài nguyên thật (và dữ liệu trong đó). Dùng
deletionPolicy: Orphan cho tài nguyên có trạng thái. |
apiVersion: v1
kind: ConfigMap
metadata:
name: argocd-notifications-cm
namespace: argocd
data:
service.slack: |
token: $slack-token
# --- Template ---
template.app-sync-failed: |
message: |
:x: *{{.app.metadata.name}}* sync THẤT BẠI
Revision: {{.app.status.sync.revision}}
Lỗi: {{.app.status.operationState.message}}
<{{.context.argocdUrl}}/applications/{{.app.metadata.name}}|Xem chi tiết>
template.app-degraded: |
message: |
:warning: *{{.app.metadata.name}}* đang DEGRADED
Trạng thái sync: {{.app.status.sync.status}}
<{{.context.argocdUrl}}/applications/{{.app.metadata.name}}|Xem chi tiết>
template.app-sync-succeeded: |
message: |
:white_check_mark: *{{.app.metadata.name}}* đã deploy
Revision: {{.app.status.sync.revision}}
Tác giả: {{(call .repo.GetCommitMetadata .app.status.sync.revision).Author}}
# --- Trigger ---
trigger.on-sync-failed: |
- when: app.status.operationState.phase in ['Error', 'Failed']
send: [app-sync-failed]
trigger.on-health-degraded: |
- when: app.status.health.status == 'Degraded'
send: [app-degraded]
trigger.on-sync-succeeded: |
- when: app.status.operationState.phase == 'Succeeded'
send: [app-sync-succeeded]
# Cảnh báo khi app lệch Git quá lâu — dấu hiệu có người sửa tay
trigger.on-out-of-sync-too-long: |
- when: app.status.sync.status == 'OutOfSync'
oncePer: app.status.sync.revision
send: [app-degraded]
# Gắn trigger vào Application bằng annotation
metadata:
annotations:
notifications.argoproj.io/subscribe.on-sync-failed.slack: deploy-alerts
notifications.argoproj.io/subscribe.on-health-degraded.slack: deploy-alerts
notifications.argoproj.io/subscribe.on-sync-succeeded.slack: deploy-log
sync-failed và health-degraded vào kênh có người
trực. sync-succeeded vào kênh log riêng (hữu ích để biết ai deploy gì, nhưng không nên gây
ồn kênh cảnh báo). Đừng alert OutOfSync ngay lập tức — nó xuất hiện bình thường
trong vài giây giữa lúc commit và lúc sync xong.
Đây là lợi ích lớn nhất của GitOps, và cũng là thứ nên diễn tập định kỳ thay vì chỉ tin là nó hoạt động.
# 1. Dựng cluster mới (Terraform / eksctl)
eksctl create cluster -f cluster-prod.yaml
# 2. Cài ArgoCD
helm upgrade --install argocd argo/argo-cd \
-n argocd --create-namespace -f argocd-values.yaml
# 3. Khôi phục credential truy cập repo (thứ DUY NHẤT không nằm trong Git)
kubectl apply -f <(aws secretsmanager get-secret-value \
--secret-id argocd/repo-creds --query SecretString --output text)
# 4. Áp dụng root application — mọi thứ còn lại tự dựng
kubectl apply -f bootstrap/root-app.yaml
# 5. Theo dõi
argocd app wait root --timeout 1800
argocd app list -o wide
argocd app rollback khi auto-sync và self-heal đang bật. Hậu quả?Câu hỏi thực tế đầu tiên khi áp dụng GitOps: tổ chức repo thế nào cho dev, staging, prod — và dùng một ArgoCD hay nhiều?
| Cách | Cấu trúc | Đánh đổi |
|---|---|---|
| Thư mục theo môi trường khuyến nghị |
apps/<service>/{dev,staging,prod}.yaml trong một repo |
Đơn giản nhất, dễ so sánh môi trường. Phân quyền bằng CODEOWNERS theo
đường dẫn file. Nhược điểm: một repo chung nên mọi người thấy cấu hình production. |
| Nhánh theo môi trường | Nhánh dev, staging, main |
Tránh. Promote thành merge giữa các nhánh, nhanh chóng sinh ra xung đột và drift. Khó biết môi trường nào đang khác môi trường nào ở đâu. |
| Repo riêng cho production | gitops-nonprod và gitops-prod |
Phân quyền rạch ròi nhất, phù hợp khi có yêu cầu tuân thủ. Nhưng phải đồng bộ thay đổi chung giữa hai repo — dễ lệch. |
| Repo riêng mỗi cluster | gitops-apse1, gitops-use1 |
Dùng khi các region thực sự độc lập về vận hành. Chi phí bảo trì cao. |
gitops-config/
├── bootstrap/
│ └── root-app.yaml # Application gốc, áp bằng tay một lần
├── argocd/
│ ├── projects/
│ │ ├── dev.yaml # AppProject: giới hạn repo, namespace, cluster
│ │ ├── staging.yaml
│ │ └── prod.yaml
│ └── applicationsets/
│ ├── dev-services.yaml
│ ├── staging-services.yaml
│ └── prod-services.yaml
├── apps/ # cấu hình từng service
│ ├── order-service/
│ │ ├── base.yaml # giá trị chung mọi môi trường
│ │ ├── dev.yaml
│ │ ├── staging.yaml
│ │ └── prod.yaml
│ ├── payment-service/
│ └── report-worker/
└── infra/ # hạ tầng trong cluster
├── cert-manager/
├── external-secrets/
├── karpenter/
├── kube-prometheus-stack/
└── aws-load-balancer-controller/
CODEOWNERS:
/apps/*/dev.yaml @myorg/developers
/apps/*/staging.yaml @myorg/developers @myorg/qa
/apps/*/prod.yaml @myorg/platform-team ← chỉ platform phê duyệt được
/argocd/** @myorg/platform-team
/infra/** @myorg/platform-team
CODEOWNERS làm được việc mà repo riêng thường được dùng để làm: developer tự merge
được dev.yaml, nhưng prod.yaml bắt buộc có phê duyệt của đội platform. Một
repo, hai mức quyền — ít chi phí bảo trì hơn nhiều so với tách repo.
# Luồng promote: cùng một image tag đi qua ba môi trường
# 1. CI build xong → bump dev TỰ ĐỘNG
yq -i '.image.tag = "a3f8c21"' apps/order-service/dev.yaml
git commit -am "chore(order-service): bump dev to a3f8c21" && git push
# 2. Test tự động trên dev xanh → bump staging TỰ ĐỘNG
yq -i '.image.tag = "a3f8c21"' apps/order-service/staging.yaml
git commit -am "chore(order-service): promote staging to a3f8c21" && git push
# 3. Promote lên prod → qua PULL REQUEST, cần phê duyệt
git checkout -b promote/order-service-a3f8c21
yq -i '.image.tag = "a3f8c21"' apps/order-service/prod.yaml
git commit -am "chore(order-service): promote prod to a3f8c21"
git push origin promote/order-service-a3f8c21
gh pr create --fill --base main
# Kiểm tra đang chạy gì ở đâu — một lệnh
grep -r 'tag:' apps/order-service/
# apps/order-service/dev.yaml: tag: "a3f8c21"
# apps/order-service/staging.yaml: tag: "a3f8c21"
# apps/order-service/prod.yaml: tag: "3f8a1c2" ← prod chậm hơn một bản
| Mô hình | Cách làm | Phù hợp khi |
|---|---|---|
| ArgoCD riêng mỗi cluster khuyến nghị |
Mỗi cluster có ArgoCD của nó, chỉ quản lý chính cluster đó
(https://kubernetes.default.svc) |
Bán kính ảnh hưởng nhỏ nhất. Mất ArgoCD của dev không ảnh hưởng production. Không cần credential cross-cluster. Chi phí: phải nâng cấp nhiều bản. |
| Một ArgoCD trung tâm | Một ArgoCD (thường ở cluster quản trị) đăng ký nhiều cluster đích | Một chỗ nhìn toàn bộ. Nhưng nó giữ credential của mọi cluster — bị chiếm quyền là mất tất cả. Và nó trở thành điểm lỗi đơn. |
| Hub với nhiều spoke | ArgoCD trung tâm cho hạ tầng, ArgoCD cục bộ cho ứng dụng | Mô hình phức tạp, chỉ đáng khi có rất nhiều cluster và đội vận hành chuyên trách. |
# Nếu dùng ArgoCD trung tâm: đăng ký cluster đích
argocd cluster add arn:aws:eks:us-east-1:123456789012:cluster/prod-use1 \
--name prod-use1 \
--namespace argocd
# Xem các cluster đã đăng ký
argocd cluster list
# ApplicationSet sinh app cho MỌI cluster đã đăng ký
# (generator cluster tự đọc danh sách)
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
name: order-service-all-regions
namespace: argocd
spec:
generators:
# Ma trận: mỗi cluster × mỗi môi trường
- matrix:
generators:
- clusters:
selector:
matchLabels:
env: prod # chỉ cluster có label này
- list:
elements:
- service: order-service
- service: payment-service
template:
metadata:
name: '{{.values.service}}-{{.name}}'
spec:
project: prod
sources:
- repoURL: https://github.com/myorg/platform-charts.git
targetRevision: v1.4.0
path: charts/generic-service
helm:
valueFiles:
- $values/apps/{{.values.service}}/base.yaml
- $values/apps/{{.values.service}}/prod.yaml
# Values riêng theo region, dùng cờ ignoreMissingValueFiles
- $values/apps/{{.values.service}}/prod-{{.metadata.labels.region}}.yaml
ignoreMissingValueFiles: true
- repoURL: https://github.com/myorg/gitops-config.git
targetRevision: main
ref: values
destination:
server: '{{.server}}'
namespace: prod
syncPolicy:
automated:
prune: true
selfHeal: true
ignoreMissingValueFiles: true là cờ cần thiết cho mô hình này: không phải region
nào cũng có file values riêng, và thiếu cờ này thì Application sẽ lỗi
values file does not exist thay vì bỏ qua file không có.
| Thứ khác nhau | Đặt ở đâu |
|---|---|
| Số replica, resource | apps/<svc>/<env>.yaml |
| Hostname, certificate ARN | apps/<svc>/<env>.yaml |
| IAM role ARN (IRSA) | apps/<svc>/<env>.yaml |
| Endpoint của DB, Redis, queue | ConfigMap qua values, hoặc ExternalSecret nếu là connection string có credential |
| Mức log, sampling rate của trace | apps/<svc>/<env>.yaml |
| Feature flag | Không nên đặt trong Git cấu hình — dùng dịch vụ feature flag để đổi được mà không cần deploy |
| Phiên bản chart | targetRevision của Application. Prod nên chậm hơn
staging một bản để staging phát hiện vấn đề trước |
ArgoCD có quyền tạo bất cứ gì ở bất cứ namespace nào. Chiếm được ArgoCD là chiếm được cluster. Mục này là những thứ phải cấu hình, không phải tuỳ chọn.
Mặc định mọi Application thuộc project default, và project đó cho phép mọi
repo, mọi namespace, mọi loại tài nguyên. Đó là cấu hình không chấp nhận được cho production.
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
name: prod
namespace: argocd
finalizers:
- resources-finalizer.argocd.argoproj.io
spec:
description: Ứng dụng production
# Chỉ cho phép đọc từ các repo này
sourceRepos:
- https://github.com/myorg/gitops-config.git
- https://github.com/myorg/platform-charts.git
- oci://123456789012.dkr.ecr.ap-southeast-1.amazonaws.com/charts
# Chỉ cho phép deploy vào namespace này, trên cluster này
destinations:
- server: https://kubernetes.default.svc
namespace: prod
- server: https://kubernetes.default.svc
namespace: prod-jobs
# Tài nguyên cấp CLUSTER được phép tạo — để trống nghĩa là KHÔNG được tạo gì
clusterResourceWhitelist: []
# Tài nguyên cấp namespace được phép
namespaceResourceWhitelist:
- { group: '', kind: ConfigMap }
- { group: '', kind: Secret }
- { group: '', kind: Service }
- { group: '', kind: ServiceAccount }
- { group: apps, kind: Deployment }
- { group: apps, kind: StatefulSet }
- { group: batch, kind: Job }
- { group: batch, kind: CronJob }
- { group: autoscaling, kind: HorizontalPodAutoscaler }
- { group: keda.sh, kind: ScaledObject }
- { group: policy, kind: PodDisruptionBudget }
- { group: networking.k8s.io, kind: Ingress }
- { group: networking.k8s.io, kind: NetworkPolicy }
- { group: external-secrets.io, kind: ExternalSecret }
- { group: monitoring.coreos.com, kind: ServiceMonitor }
# Chặn tường minh những thứ nguy hiểm
namespaceResourceBlacklist:
- { group: rbac.authorization.k8s.io, kind: Role }
- { group: rbac.authorization.k8s.io, kind: RoleBinding }
# Ai được làm gì trong project này
roles:
- name: developer
description: Xem và sync, không sửa được Application
policies:
- p, proj:prod:developer, applications, get, prod/*, allow
- p, proj:prod:developer, applications, sync, prod/*, allow
- p, proj:prod:developer, logs, get, prod/*, allow
groups:
- myorg:developers
- name: admin
policies:
- p, proj:prod:admin, applications, *, prod/*, allow
groups:
- myorg:platform-team
# Chỉ cho phép sync production trong giờ làm việc
syncWindows:
- kind: allow
schedule: "0 8 * * 1-5"
duration: 10h
applications: ['*']
manualSync: true # cho phép sync tay ngoài giờ khi có sự cố
- kind: deny
schedule: "0 0 * * 0,6"
duration: 24h
applications: ['*']
manualSync: true
clusterResourceWhitelist: [] là dòng quan trọng nhất ở đây. Nó chặn Application
production tạo ClusterRole, ClusterRoleBinding, CRD hay Namespace. Nghĩa là nếu ai đó commit một
manifest tạo ClusterRoleBinding gắn cluster-admin, ArgoCD từ chối
thay vì áp dụng. Đây là lớp phòng vệ chống cả sai sót và tấn công qua pull request.
syncWindows — cân nhắc kỹ trước khi dùng. Nó chặn deploy ngoài giờ làm việc, hữu
ích để tránh deploy lúc không ai trực. Nhưng nó cũng chặn self-heal: nếu có sai lệch xảy ra lúc
2 giờ sáng, ArgoCD sẽ không tự sửa. Luôn đặt manualSync: true để còn can thiệp được khi
có sự cố.
apiVersion: v1
kind: ConfigMap
metadata:
name: argocd-rbac-cm
namespace: argocd
data:
# Mặc định chỉ đọc — quan trọng, vì mặc định của ArgoCD rộng hơn thế
policy.default: role:readonly
policy.csv: |
# ---- Developer: xem mọi thứ, sync chỉ ở dev ----
p, role:dev, applications, get, */*, allow
p, role:dev, applications, sync, dev/*, allow
p, role:dev, applications, action/*, dev/*, allow
p, role:dev, logs, get, */*, allow
p, role:dev, exec, create, dev/*, allow
# ---- QA: thêm quyền sync staging ----
p, role:qa, applications, sync, staging/*, allow
# ---- Platform: toàn quyền ----
p, role:platform, applications, *, */*, allow
p, role:platform, clusters, *, *, allow
p, role:platform, repositories, *, *, allow
p, role:platform, projects, *, *, allow
# ---- CHẶN tường minh: không ai được exec vào pod production ----
p, role:platform, exec, create, prod/*, deny
# ---- Map nhóm từ IdP ----
g, myorg:developers, role:dev
g, myorg:qa, role:dev
g, myorg:qa, role:qa
g, myorg:platform-team, role:platform
scopes: '[groups, email]'
exec, create là quyền cần chú ý đặc biệt. Nó cho phép mở terminal vào pod qua giao
diện ArgoCD — tiện khi debug dev, nhưng với production thì đó là đường vào bỏ qua mọi audit của
kubectl. Dòng deny ở trên chặn cả role:platform; ai cần vào pod
production thì dùng kubectl với danh tính cá nhân, để lại dấu vết trong CloudTrail.
base64 là encoding, không
phải mã hoá — giải ra trong một lệnh. Ba cách đúng:
| External Secrets Operator khuyến nghị |
Git chứa ExternalSecret (chỉ là tham chiếu), giá trị thật ở AWS Secrets
Manager. Có rotation, có audit qua CloudTrail. Xem
chặng 02, mục 3. |
| Sealed Secrets | Mã hoá bằng public key của cluster, commit được an toàn. Chỉ controller trong cluster giải mã được. Đơn giản hơn ESO nhưng phải tự quản lý luân chuyển khoá. |
| SOPS + KMS | Mã hoá file bằng KMS, dùng với plugin argocd-vault-plugin hoặc
ksops. Linh hoạt nhưng thêm một lớp phụ thuộc vào ArgoCD. |
# Cấu hình ArgoCD bỏ qua Secret do ESO tạo — nếu không nó sẽ báo OutOfSync mãi
# argocd-cm.yaml
data:
resource.customizations.ignoreDifferences.all: |
managedFieldsManagers:
- external-secrets
# Hoặc đánh dấu trên chính ExternalSecret
metadata:
annotations:
argocd.argoproj.io/compare-options: IgnoreExtraneous
# Bắt buộc commit phải có chữ ký GPG — chặn commit giả mạo vào repo GitOps
# AppProject
spec:
signatureKeys:
- keyID: 4AEE18F83AFDEB23
# Thêm khoá công khai vào ArgoCD
kubectl -n argocd create cm argocd-gpg-keys-cm \
--from-file=4AEE18F83AFDEB23=pubkey.asc \
--dry-run=client -o yaml | kubectl apply -f -
Với cấu hình này, ArgoCD từ chối sync nếu commit ở targetRevision
không được ký bởi khoá đã đăng ký. Hữu ích cho môi trường có yêu cầu tuân thủ, nhưng cần quy trình quản
lý khoá cho cả CI (vì Jenkins cũng commit vào repo này).
| Mặc định | Vấn đề và cách sửa |
|---|---|
Tài khoản admin bật |
Một mật khẩu dùng chung, không truy vết được ai làm gì. Cấu hình SSO rồi
admin.enabled: false. |
policy.default rộng |
Đặt role:readonly. Cấp quyền tường minh qua policy.csv. |
Project default cho phép mọi thứ |
Tạo AppProject riêng cho từng môi trường. Hoặc siết chính project
default lại. |
Ingress internet-facing |
Đổi sang internal. ArgoCD không có lý do gì để phơi ra internet. |
Không có clusterResourceWhitelist |
Application có thể tạo ClusterRoleBinding. Đặt [] cho project ứng dụng. |
Không giới hạn sourceRepos |
Application có thể trỏ vào repo bất kỳ, kể cả repo của người ngoài. Liệt kê tường minh. |
# Kiểm tra nhanh cấu hình hiện tại
kubectl -n argocd get cm argocd-cm -o jsonpath='{.data.admin\.enabled}'
kubectl -n argocd get cm argocd-rbac-cm -o jsonpath='{.data.policy\.default}'
kubectl -n argocd get appproject default -o yaml | grep -A3 'clusterResourceWhitelist'
kubectl -n argocd get ingress -o jsonpath='{.items[*].metadata.annotations}' | tr ',' '\n' | grep scheme
# Xem quyền thật của ServiceAccount ArgoCD
kubectl auth can-i --list --as=system:serviceaccount:argocd:argocd-application-controller | head -20
clusterResourceWhitelist: [] trong AppProject có tác dụng gì?| Hạng mục | Vì sao | |
|---|---|---|
| ☐ | Không ai chạy kubectl apply hay helm upgrade vào production |
Mọi thay đổi qua Git. Đây là nguyên tắc duy nhất mà nếu phá vỡ thì mọi lợi ích còn lại biến mất. |
| ☐ | Tách repo code và repo cấu hình | Phân quyền khác nhau, và tránh vòng lặp CI khi bump tag. |
| ☐ | Repo cấu hình có CODEOWNERS cho prod.yaml |
Developer tự merge dev được, prod bắt buộc phê duyệt. |
| ☐ | Image tag là git SHA, không bao giờ latest |
Tag động làm ArgoCD không phát hiện được thay đổi và rollback vô hiệu. |
| ☐ | Giá trị secret thật không nằm trong Git | base64 không phải mã hoá. Dùng ESO với Secrets Manager. |
| Hạng mục | Vì sao | |
|---|---|---|
| ☐ | targetRevision là tag hoặc SHA cho production, không phải HEAD |
HEAD nghĩa là mọi commit vào chart đều lên production ngay, kể cả commit chưa test. |
| ☐ | Có ignoreDifferences cho /spec/replicas nếu dùng HPA/KEDA |
Không có thì ArgoCD và autoscaler tranh nhau: app OutOfSync liên tục, và self-heal
kéo replicas về giá trị trong Git. |
| ☐ | prune: true được bật có ý thức |
Thiếu nó thì tài nguyên xoá khỏi Git vẫn tồn tại trong cluster mãi. Có nó thì cẩn thận với lỗi đường dẫn — xem mục 5. |
| ☐ | Tài nguyên có trạng thái có Prune=false hoặc deletionPolicy: Orphan |
Prune một PVC hoặc một RDS do Crossplane quản lý là mất dữ liệu. |
| ☐ | Có retry với backoff trong syncPolicy |
Sync thất bại do lỗi tạm thời (webhook admission chưa sẵn sàng) sẽ tự thử lại. |
| ☐ | Webhook từ Git tới ArgoCD đã cấu hình | Không có thì chờ tới 3 phút mỗi lần deploy. |
| ☐ | Có revisionHistoryLimit hợp lý (5–10) |
Giữ đủ để rollback, không quá nhiều để phình object trong cluster. |
| Hạng mục | Vì sao | |
|---|---|---|
| ☐ | ArgoCD không phơi ra internet (scheme: internal) |
Chiếm được ArgoCD là chiếm được cluster. |
| ☐ | Tài khoản admin đã tắt, dùng SSO với MFA |
Mật khẩu dùng chung không truy vết được ai làm gì. |
| ☐ | policy.default: role:readonly |
Mặc định của ArgoCD rộng hơn mức an toàn. |
| ☐ | Có AppProject riêng cho từng môi trường | Project default cho phép mọi repo, mọi namespace, mọi loại tài nguyên. |
| ☐ | clusterResourceWhitelist: [] cho project ứng dụng |
Chặn Application tạo ClusterRoleBinding — chống cả sai sót và tấn công qua pull request. |
| ☐ | sourceRepos liệt kê tường minh |
Không có thì Application trỏ được vào repo bất kỳ. |
| ☐ | destinations giới hạn namespace và cluster |
Application của dev không deploy được vào namespace prod. |
| ☐ | exec, create bị deny cho production |
Terminal qua giao diện ArgoCD bỏ qua audit của kubectl. |
| ☐ | Nếu dùng syncWindows: có manualSync: true |
Nếu không, self-heal bị chặn ngoài giờ và bạn không can thiệp được khi có sự cố. |
| Hạng mục | Vì sao | |
|---|---|---|
| ☐ | Có thông báo cho sync-failed và health-degraded |
Sync thất bại im lặng nghĩa là cluster đứng ở trạng thái cũ mà không ai biết. |
| ☐ | Sync wave xếp đúng thứ tự phụ thuộc | Namespace và CRD trước, ExternalSecret trước Deployment, migration trước app. |
| ☐ | Job migration khai cả helm.sh/hook và argocd.argoproj.io/hook |
ArgoCD bỏ qua annotation của Helm. |
| ☐ | Migration tương thích ngược | Rollback trong Git không hoàn tác được schema database. |
| ☐ | Promote chỉ đổi image tag, không đổi values khác | Nếu phải đổi values để lên prod thì staging không đại diện cho prod. |
| ☐ | Có runbook khôi phục thảm hoạ, đã diễn tập | Năm thứ không nằm trong Git: repo credential, secret, dữ liệu stateful, DNS, certificate. |
| ☐ | Biết cách rollback khẩn cấp đúng thứ tự | Tắt auto-sync trước khi argocd app rollback, nếu không self-heal kéo về lại
phiên bản lỗi. |
ignoreDifferences cho replicas → ArgoCD và HPA tranh nhau, pod bị
scale về giá trị trong Git giữa lúc cao tảitargetRevision: HEAD cho production → mọi commit vào chart lên prod ngay lập tứcargocd app rollback mà không tắt auto-sync → sự cố quay lại sau vài chục giâydefault không bị siết → một manifest tạo được cluster-admin