ArgoCD GitOps
GitOps continuous delivery — tự động deploy từ Gitea lên K3s.
Bối cảnh & Lý do triển khai
GitOps là mô hình vận hành mà trạng thái mong muốn của hệ thống được định nghĩa trong Git, và một agent tự động reconcile trạng thái thực tế về đúng với Git. ArgoCD là công cụ GitOps phổ biến nhất cho Kubernetes — nó liên tục theo dõi các Helm chart và manifest YAML trên Gitea, phát hiện drift, và tự động (hoặc theo yêu cầu) đồng bộ về trạng thái mong muốn.
ArgoCD được triển khai trực tiếp trên K3s cluster (không cần VM riêng), dùng Traefik ingress cho HTTPS, cert-manager cho TLS tự động từ step-CA, Authentik cho SSO, và Gitea làm nguồn Git nội bộ. Toàn bộ workload trên cluster sẽ được quản lý qua pattern "App of Apps".
| Mục | Nội dung |
|---|---|
| Ứng dụng trong doanh nghiệp | CI/CD pipeline cuối cùng — sau khi Gitea build xong, ArgoCD deploy lên K3s |
| Tác dụng chính | Declarative deployment, automatic sync, drift detection, rollback 1 click |
| Nếu không triển khai | Deploy thủ công bằng kubectl, dễ configuration drift, không audit trail |
| Các service phụ thuộc vào đây | Tất cả workload chạy trên K3s được ArgoCD quản lý |
Ngày cập nhật: 2026-10-15 (nâng ArgoCD từ v2.11.3 lên v3.5.5; K3s trên Ubuntu Server 24.04 theo bài 28)
Danh sách máy chủ & IP liên quan
Bảng dưới liệt kê các máy chủ mà bài này tạo hoặc kết nối tới. Địa chỉ, VMID, VLAN và node lấy từ bảng quy hoạch chung của lab, dùng thống nhất cho cả bộ bài lab.
| Máy chủ | IP | VLAN · Node | Vai trò trong bài này |
|---|---|---|---|
| K3s Ingress VIP (MetalLB + Traefik) | 10.11.65.100 | 65 (SRV) · — (VIP) | Điểm vào HTTPS của ArgoCD (argocd.hoatranlabs.local): Traefik IngressRoute chấm dứt TLS, chuyển HTTP cổng 80 tới argocd-server. |
| K3s cluster (3 control plane + 3 worker) · VM 260–265 | 10.11.65.60–65 | 65 (SRV) · node1–node3 | Cụm K3s HA (bài 28) chạy ArgoCD trong namespace argocd, không có VM riêng; tạo registries.yaml trỏ Harbor trên mọi node. |
| pihole (Pi-hole DNS) · VM247 | 10.11.45.53 | 45 (MGMT) · node3 | Phân giải argocd.hoatranlabs.local về 10.11.65.100 bằng bản ghi Local DNS thêm ở mục 4.1 (bài 12). |
| step-ca (step-CA PKI) · VM242 | 10.11.25.42 | 25 (SEC) · node1 | Cấp chứng chỉ TLS cho argocd.hoatranlabs.local qua ClusterIssuer step-ca-issuer của cert-manager (bài 13). |
| gitea (Gitea + Actions) · VM240 | 10.11.45.40 | 45 (MGMT) · node2 | Nguồn Git: ArgoCD đọc repo k8s-manifests (App of Apps) bằng user argocd-bot; webhook push gọi /api/webhook của ArgoCD (bài 22). |
| authentik (Authentik SSO) · VM234 | 10.11.25.40 | 25 (SEC) · node1 | Nhà cung cấp OIDC cho nút Login via Authentik; nhóm argocd-admins và argocd-readonly ánh xạ sang role admin và readonly (bài 14). |
| mailu (Mailu Mail Server) · VM246 | 10.11.35.46 | 35 (DMZ) · node2 | Relay SMTP cổng 587 (STARTTLS, có xác thực) cho ArgoCD Notifications gửi email từ [email protected] (bài 16). |
| harbor (Harbor Registry) · VM239 | 10.11.45.39 | 45 (MGMT) · node2 | Registry chứa image cho workload do ArgoCD triển khai; mirror và credentials khai báo trong registries.yaml trên mọi node K3s (bài 21). |
Gateway của mỗi VLAN là địa chỉ .1. Tên DNS nội bộ do Pi-hole phân giải (bài 12). Tên in đậm là hostname; FQDN = hostname + .hoatranlabs.local. ArgoCD chạy trong namespace argocd của K3s nên không có VM riêng; truy cập qua argocd.hoatranlabs.local, địa chỉ ở dòng K3s Ingress VIP.
Thông tin Deployment
ArgoCD không có VM riêng — được cài đặt như một namespace trên K3s cluster (bài 28).
| Thông số | Giá trị |
|---|---|
| Cluster | K3s HA (bài 28) |
| Namespace | argocd |
| ArgoCD version | v3.5.5 (bản stable mới nhất ngày 2026-10-15) |
| URL | https://argocd.hoatranlabs.local |
| Git source | https://gitea.hoatranlabs.local (VM240) |
| Ingress | Traefik (IP 10.11.65.100) |
| TLS | cert-manager + step-CA ACME |
| SSO | Authentik OIDC |
| Notifications | Email qua Mailu SMTP (VM246) |
Phiên bản phần mềm sử dụng (đã xác minh 2026-10-15):
| Thành phần | Phiên bản dùng trong bài | Ghi chú |
|---|---|---|
| Argo CD (server) | v3.5.5 (nâng từ v2.11.3) | Argo CD chỉ vá ba minor mới nhất (docs "Release Process and Cadence"); ngày 2026-10-12 đó là 3.5 (v3.5.5), 3.4 (v3.4.11) và 3.3 (v3.3.16) nên v2.11 đã hết được vá. v3.5 được kiểm với Kubernetes 1.33 đến 1.36, khớp K3s v1.36.5 của bài 28. Cài bằng kubectl apply --server-side --force-conflicts vì CRD ApplicationSet vượt giới hạn annotation của client-side apply (docs Getting Started). |
| argocd CLI | v3.5.5 | Cùng phiên bản với server (mục 3.1). |
| Hệ điều hành / cluster | K3s v1.36.5+k3s1 trên Ubuntu Server 24.04 LTS (bài 28) | ArgoCD chạy trong cluster nên không cài gói lên VM; chỉ máy admin cần kubectl và argocd. |
| Traefik, cert-manager, step-CA, Gitea, Authentik, Mailu, Harbor | theo bài 28, 13, 22, 14, 16, 21 | Bài này không ghim thêm phiên bản của các thành phần đó. |
Điểm khác của Argo CD 3.x so với 2.11 có ảnh hưởng tới bài này (theo trang nâng cấp 2.14 sang 3.0 và các trang 3.x trên argo-cd.readthedocs.io): (1) cài bằng server-side apply (mục 2.1); (2) theo dõi tài nguyên bằng annotation thay cho label và có sẵn resource.exclusions mặc định, không ảnh hưởng cài mới; (3) RBAC tách quyền update/*, delete/* cho tài nguyên con và bắt buộc quyền logs, get để xem log, role dựng sẵn role:admin và role:readonly đã có các quyền này (đối chiếu assets/builtin-policy.csv của v3.5.5); (4) bỏ các metric argocd_app_sync_status, argocd_app_health_status, argocd_app_created_time (dữ liệu nằm trong nhãn của argocd_app_info), dashboard hoặc alert cũ dùng tên metric đó phải sửa (mục 4.4); (5) cấu hình repo kiểu cũ trong argocd-cm không còn được hỗ trợ, bài này dùng argocd repo add (lưu thành Secret) nên không bị ảnh hưởng. Hành vi đầy đủ trên K3s v1.36 cần kiểm lại trên máy thật.
Điều kiện tiên quyết
Trước khi cài ArgoCD, xác minh K3s cluster đã có đủ:
# Kiểm tra cluster sẵn sàng
kubectl get nodes
# Expected: 6 nodes Ready
# Kiểm tra Traefik đã có External IP
kubectl -n kube-system get svc traefik
# Expected: EXTERNAL-IP = 10.11.65.100
# Kiểm tra cert-manager và ClusterIssuer
kubectl get clusterissuer step-ca-issuer
# Expected: READY=True
# Kiểm tra DNS resolve (nslookup thuộc gói bind9-dnsutils, bản Ubuntu 24.04 minimized không cài sẵn: apt install -y bind9-dnsutils)
nslookup argocd.hoatranlabs.local 10.11.45.53
# Expected: trả về 10.11.65.100
Cài đặt ArgoCD
Tạo namespace và cài manifest · Cấu hình Ingress qua Traefik · Lấy mật khẩu admin ban đầu
2.1 Tạo namespace và cài manifest
# Tạo namespace
kubectl create namespace argocd
# Cài ArgoCD v3.5.5 (ghim tag thay vì nhánh stable để cài lại cho kết quả giống nhau)
# --server-side --force-conflicts là bắt buộc: CRD ApplicationSet vượt giới hạn 262KB annotation của client-side apply
ARGOCD_VERSION=v3.5.5
kubectl apply -n argocd --server-side --force-conflicts \
-f https://raw.githubusercontent.com/argoproj/argo-cd/${ARGOCD_VERSION}/manifests/install.yaml
# Chờ tất cả pods ArgoCD Ready
kubectl -n argocd wait --for=condition=ready pod --all --timeout=180s
# Kiểm tra
kubectl -n argocd get pods
2.2 Cấu hình Ingress qua Traefik
ArgoCD server cần được expose qua HTTPS. Traefik chấm dứt TLS, rồi forward HTTP thuần (cổng 80) đến argocd-server — server chạy ở chế độ --insecure (bật bằng server.insecure: "true" trong ConfigMap argocd-cmd-params-cm, ở cuối mục này) nên backend là HTTP, không phải HTTPS.
cat <<'EOF' | kubectl apply -f -
# IngressRoute cho ArgoCD (Traefik CRD)
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: argocd-server
namespace: argocd
spec:
entryPoints:
- websecure
routes:
- kind: Rule
match: Host(`argocd.hoatranlabs.local`)
priority: 10
services:
- name: argocd-server
port: 80 # backend HTTP vì argocd-server chạy --insecure (TLS đã kết thúc ở Traefik)
passHostHeader: true
tls:
secretName: argocd-server-tls
---
# Certificate từ step-CA
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: argocd-server-cert
namespace: argocd
spec:
secretName: argocd-server-tls
issuerRef:
name: step-ca-issuer
kind: ClusterIssuer
dnsNames:
- argocd.hoatranlabs.local
EOF
# Chạy argocd-server ở chế độ --insecure (TLS đã kết thúc ở Traefik): đặt server.insecure trong
# ConfigMap argocd-cmd-params-cm (cách chuẩn của ArgoCD, không patch args của Deployment) rồi restart
kubectl -n argocd patch configmap argocd-cmd-params-cm \
--type merge -p '{"data":{"server.insecure":"true"}}'
kubectl -n argocd rollout restart deployment argocd-server
kubectl -n argocd rollout status deployment argocd-server
2.3 Lấy mật khẩu admin ban đầu
# Lấy initial admin password
kubectl -n argocd get secret argocd-initial-admin-secret \
-o jsonpath="{.data.password}" | base64 -d; echo
# Đăng nhập lần đầu tại https://argocd.hoatranlabs.local
# Username: admin
# Password: <giá trị trên>
Cấu hình
Cài ArgoCD CLI · Đổi mật khẩu admin · Kết nối Gitea Repository
3.1 Cài ArgoCD CLI
# Trên máy admin (hoặc bất kỳ node nào)
ARGOCD_VERSION=v3.5.5 # cùng phiên bản với server cài ở mục 2.1
curl -sSL -o /usr/local/bin/argocd \
https://github.com/argoproj/argo-cd/releases/download/$ARGOCD_VERSION/argocd-linux-amd64
chmod +x /usr/local/bin/argocd
argocd version --client
# Login
argocd login argocd.hoatranlabs.local \
--username admin \
--password $(kubectl -n argocd get secret argocd-initial-admin-secret \
-o jsonpath="{.data.password}" | base64 -d) \
--grpc-web
3.2 Đổi mật khẩu admin
argocd account update-password \
--current-password $(kubectl -n argocd get secret argocd-initial-admin-secret \
-o jsonpath="{.data.password}" | base64 -d) \
--new-password "Hoatran@2024!"
# Xóa initial secret sau khi đổi xong
kubectl -n argocd delete secret argocd-initial-admin-secret
3.3 Kết nối Gitea Repository
# ArgoCD (repo-server) không dùng trust store của node nên chưa tin root CA của step-CA:
# khai báo root CA cho từng host HTTPS mà ArgoCD kết nối. File root CA là file đã phát lên node ở bài 28, mục 4.2
# (copy file này sang máy admin nếu chạy lệnh argocd từ máy khác).
argocd cert add-tls gitea.hoatranlabs.local \
--from /usr/local/share/ca-certificates/hoatranlabs-root.crt
argocd cert list --cert-type https
# Cách khai báo thay thế: ConfigMap argocd-tls-certs-cm (key = hostname, value = PEM của root CA).
# Thêm entry tương tự cho harbor.hoatranlabs.local nếu sau này dùng Harbor làm Helm/OCI repo của ArgoCD.
# Thêm Gitea server vào ArgoCD
argocd repocreds add https://gitea.hoatranlabs.local \
--username argocd-bot \
--password "Hoatran@2024!" \
--upsert
# Verify kết nối
argocd repocreds list
# Thêm repository cụ thể (infra repo)
argocd repo add https://gitea.hoatranlabs.local/gitadmin/k8s-manifests \
--username argocd-bot \
--password "Hoatran@2024!" \
--name k8s-manifests
gitadmin và user bot argocd-bot đã tạo ở bài 22 (mật khẩu/token của bot lấy theo bài 22; bot cần quyền đọc repo). Tạo repo k8s-manifests thuộc gitadmin với cấu trúc App of Apps (xem mục 3.5).
3.4 Authentik SSO (OIDC)
# BƯỚC 1: Trên Authentik Web UI (https://authentik.hoatranlabs.local:9443)
# Applications → Providers → Create → OAuth2/OpenID Provider:
# Name: argocd
# Client ID: argocd
# Client Secret: [CHANGE_ME — ghi lại]
# Redirect URIs:
# https://argocd.hoatranlabs.local/auth/callback
# Scopes: openid, profile, email, groups
# Applications → Create → chọn provider trên
# Tạo Group: argocd-admins, argocd-readonly → thêm users
# BƯỚC 2: Cập nhật ArgoCD ConfigMap
# Cert HTTPS của Authentik do step-CA cấp và argocd-server không dùng trust store của node,
# nên khai báo rootCA (root CA của step-CA) ngay trong oidc.config
cat > /tmp/argocd-cm-patch.yaml << 'EOF'
data:
url: https://argocd.hoatranlabs.local
oidc.config: |
name: Authentik
issuer: https://authentik.hoatranlabs.local:9443/application/o/argocd/
clientID: argocd
clientSecret: $oidc.authentik.clientSecret
requestedScopes:
- openid
- profile
- email
- groups
rootCA: |
EOF
# nối PEM của root CA (thụt vào 6 khoảng trắng để nằm trong khối rootCA)
sed 's/^/ /' /usr/local/share/ca-certificates/hoatranlabs-root.crt >> /tmp/argocd-cm-patch.yaml
kubectl -n argocd patch configmap argocd-cm --type=merge --patch-file /tmp/argocd-cm-patch.yaml
# Tạo Secret chứa OIDC client secret
kubectl -n argocd create secret generic argocd-secret \
--from-literal=oidc.authentik.clientSecret="[CHANGE_ME]" \
--dry-run=client -o yaml | kubectl apply -f -
# BƯỚC 3: Cấu hình RBAC mapping Authentik groups → ArgoCD roles
kubectl -n argocd patch configmap argocd-rbac-cm --type=merge -p '
{
"data": {
"policy.csv": "g, argocd-admins, role:admin\ng, argocd-readonly, role:readonly\n",
"scopes": "[groups, email]"
}
}'
kubectl -n argocd rollout restart deployment argocd-server
3.5 App of Apps Pattern
Tạo cấu trúc repository trên Gitea (k8s-manifests):
k8s-manifests/
├── apps/
│ ├── root-app.yaml # App of Apps root
│ ├── monitoring.yaml # kube-prometheus-stack app
│ ├── cert-manager.yaml # cert-manager app
│ └── metallb.yaml # MetalLB app
├── charts/
│ ├── monitoring/
│ │ └── values.yaml
│ └── cert-manager/
│ └── values.yaml
└── manifests/
└── namespaces.yaml
# Root App of Apps — đây là ứng dụng đầu tiên đăng ký vào ArgoCD
# Sau đó root-app.yaml sẽ tự tạo tất cả apps con
cat > /tmp/root-app.yaml << 'EOF'
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: root
namespace: argocd
finalizers:
- resources-finalizer.argocd.argoproj.io
spec:
project: default
source:
repoURL: https://gitea.hoatranlabs.local/gitadmin/k8s-manifests
targetRevision: main
path: apps
destination:
server: https://kubernetes.default.svc
namespace: argocd
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- CreateNamespace=true
EOF
kubectl apply -f /tmp/root-app.yaml
# Verify
argocd app list
argocd app get root
3.6 ArgoCD Notifications — Email qua Mailu
# Cài ArgoCD Notifications Controller (đã có trong install.yaml v3.5.5)
# Chỉ cần cấu hình SMTP
# SMTP theo bài 16: mailu.hoatranlabs.local (10.11.35.46), cổng 587 STARTTLS có xác thực,
# mailbox dịch vụ [email protected]
# TLS: cổng 587 dùng STARTTLS và ArgoCD kiểm tra chứng chỉ Mailu theo đúng giá trị host. Cert Mailu có SAN
# mailu.hoatranlabs.local (bài 16) nên TÊN khớp (dùng hostname, không dùng IP). Phần còn lại là CA: container
# argocd-notifications-controller không dùng trust store của node nên chưa tin root CA step-CA; lệnh
# `kubectl set env ... SSL_CERT_DIR` ở cuối mục này cho container tin root CA đã khai báo ở mục 3.3 (argocd-tls-certs-cm).
# Chỉ khi thử nghiệm mới dùng `insecure_skip_verify: true` trong service.email.mailu để bỏ qua kiểm tra
# Lưu ý định dạng: mỗi giá trị service./template./trigger. là chuỗi YAML thuần (KHÔNG có ký tự `|` đầu chuỗi — `|` chỉ dùng khi
# viết ConfigMap bằng file YAML); trong biểu thức trigger, giá trị chuỗi phải nằm trong nháy kép như "Succeeded"
kubectl -n argocd patch configmap argocd-notifications-cm --type=merge -p '
{
"data": {
"service.email.mailu": "host: mailu.hoatranlabs.local\nport: 587\nfrom: [email protected]\nusername: [email protected]\npassword: $email-password\n",
"template.app-deployed": "email:\n subject: \"ArgoCD: {{.app.metadata.name}} deployed to {{.app.spec.destination.namespace}}\"\nmessage: \"Application {{.app.metadata.name}} has been deployed.\\nSync status: {{.app.status.sync.status}}\\nHealth: {{.app.status.health.status}}\"\n",
"template.app-health-degraded": "email:\n subject: \"ArgoCD ALERT: {{.app.metadata.name}} health degraded\"\nmessage: \"Application {{.app.metadata.name}} health is {{.app.status.health.status}}.\\nMessage: {{.app.status.conditions}}\"\n",
"trigger.on-deployed": "- when: app.status.operationState.phase in [\"Succeeded\"]\n send: [app-deployed]\n",
"trigger.on-health-degraded": "- when: app.status.health.status == \"Degraded\"\n send: [app-health-degraded]\n"
}
}'
# Secret cho email password
kubectl -n argocd create secret generic argocd-notifications-secret \
--from-literal=email-password="Noreply@Mailu2024!" \
--dry-run=client -o yaml | kubectl apply -f -
# Patch default project để enable notifications
kubectl -n argocd annotate appproject default \
notifications.argoproj.io/subscribe.on-deployed.mailu="[email protected]" \
notifications.argoproj.io/subscribe.on-health-degraded.mailu="[email protected]"
# Cho argocd-notifications-controller tin root CA step-CA để xác thực STARTTLS của Mailu: Deployment này đã mount sẵn
# ConfigMap argocd-tls-certs-cm vào /app/config/tls (file root CA khai báo bằng `argocd cert add-tls` ở mục 3.3 nằm trong đó);
# SSL_CERT_DIR là biến Go đọc thêm chứng chỉ CA từ thư mục này. Lệnh này làm Deployment tự khởi động lại.
kubectl -n argocd set env deployment/argocd-notifications-controller SSL_CERT_DIR=/app/config/tls
Tích hợp với hạ tầng
Pi-hole DNS · Gitea Webhook — tự động sync khi push · Kết nối với Harbor Registry
4.1 Pi-hole DNS
# Thêm DNS record vào Pi-hole
# Admin panel: http://10.11.45.53/admin → Settings → Local DNS Records
argocd.hoatranlabs.local → 10.11.65.100
4.2 Gitea Webhook — tự động sync khi push
# Trên Gitea Web UI (https://gitea.hoatranlabs.local)
# Repository k8s-manifests → Settings → Webhooks → Add Webhook → Gitea
# URL: https://argocd.hoatranlabs.local/api/webhook
# Content type: application/json
# Secret: [CHANGE_ME — lưu vào ArgoCD]
# Events: Push Events
# Thêm webhook secret vào ArgoCD. ArgoCD không có khóa webhook.gitea.secret: Gitea gửi kèm header X-Gogs-*
# nên ArgoCD xử lý webhook theo chế độ Gogs -> dùng khóa webhook.gogs.secret
kubectl -n argocd patch secret argocd-secret --type=merge \
-p '{"stringData":{"webhook.gogs.secret":"[CHANGE_ME]"}}'
4.3 Kết nối với Harbor Registry
# Để ArgoCD deploy images từ Harbor (VM239)
# Thêm Harbor credentials vào K3s nodes (trong file K3s registries config)
# Đây là bước TẠO file /etc/rancher/k3s/registries.yaml duy nhất của cluster (mới có mục Harbor).
# Bài 31 (Nexus mirror) sẽ GỘP thêm các mục mirrors vào chính file này — không ghi đè.
# Root CA /usr/local/share/ca-certificates/hoatranlabs-root.crt đã được phát lên các node ở bài 28, mục 4.2.
# Trên TẤT CẢ K3s nodes:
cat > /etc/rancher/k3s/registries.yaml << 'EOF'
mirrors:
"harbor.hoatranlabs.local":
endpoint:
- "https://harbor.hoatranlabs.local"
configs:
"harbor.hoatranlabs.local":
auth:
username: admin
password: "Admin@Harbor2024!"
tls:
ca_file: /usr/local/share/ca-certificates/hoatranlabs-root.crt
EOF
systemctl restart k3s # hoặc k3s-agent trên worker nodes
4.4 Prometheus Monitoring
# ArgoCD tự expose metrics tại port 8082
# Thêm ServiceMonitor (nếu dùng kube-prometheus-stack)
cat <<'EOF' | kubectl apply -f -
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
name: argocd-metrics
namespace: argocd
labels:
release: kube-prometheus-stack
spec:
selector:
matchLabels:
app.kubernetes.io/name: argocd-metrics
endpoints:
- port: metrics
---
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
name: argocd-server-metrics
namespace: argocd
labels:
release: kube-prometheus-stack
spec:
selector:
matchLabels:
app.kubernetes.io/name: argocd-server-metrics
endpoints:
- port: metrics
EOF
4.5 PBS Backup
ArgoCD state được lưu trong Kubernetes etcd — đã được backup trong bài 28 (K3s PBS backup). Không cần backup riêng. Để restore: apply lại ArgoCD manifest và kubectl apply root-app.yaml.
Kiểm tra & Xác minh
# 1. Kiểm tra tất cả ArgoCD pods Running
kubectl -n argocd get pods
# Expected: argocd-server, argocd-repo-server, argocd-application-controller,
# argocd-applicationset-controller, argocd-notifications-controller
# argocd-redis — tất cả Running
# 2. Kiểm tra Ingress và TLS
curl -sk https://argocd.hoatranlabs.local/healthz
# Expected: {"status":"ok"}
# Kiểm tra cert hợp lệ
echo | openssl s_client -connect argocd.hoatranlabs.local:443 -servername argocd.hoatranlabs.local 2>/dev/null \
| openssl x509 -noout -dates -subject
# Expected: CN=argocd.hoatranlabs.local, notAfter trong tương lai
# 3. Login bằng CLI
argocd login argocd.hoatranlabs.local \
--username admin \
--password "Hoatran@2024!" \
--grpc-web
argocd version
# 4. Kiểm tra Gitea repo kết nối
argocd repo list
# Expected: STATUS=Successful cho https://gitea.hoatranlabs.local/...
# 5. Kiểm tra App of Apps
argocd app list
argocd app get root
# Expected: STATUS=Synced, HEALTH=Healthy
# 6. Test deploy một app mới
# Commit một file manifest thay đổi vào Gitea k8s-manifests repo
# Sau tối đa 3 phút (poll interval mặc định), ArgoCD tự detect và sync
# 7. Test OIDC login
# Mở browser: https://argocd.hoatranlabs.local
# Click "Login via Authentik"
# Đăng nhập với user thuộc group argocd-admins
# Expected: vào được dashboard với full admin quyền
# 8. Kiểm tra notification
kubectl -n argocd logs deploy/argocd-notifications-controller | grep -i "sending notification"
Troubleshooting
| Vấn đề | Nguyên nhân | Giải pháp |
|---|---|---|
UI/CLI báo ERR_TOO_MANY_REDIRECTS (vòng lặp redirect) | argocd-server chưa chạy --insecure nên tự chuyển HTTP → HTTPS, trong khi Traefik đã chấm dứt TLS | Kiểm tra kubectl -n argocd get cm argocd-cmd-params-cm -o yaml có server.insecure: "true"; sau khi sửa chạy kubectl -n argocd rollout restart deployment argocd-server |
| Ingress 502 Bad Gateway | IngressRoute và chế độ của argocd-server không khớp: server đã chạy --insecure (HTTP) nhưng IngressRoute trỏ HTTPS (port: 443 / scheme: https) | Kiểm tra server.insecure: "true" đã áp dụng và argocd-server đã restart; IngressRoute phải trỏ argocd-server port 80 (HTTP), không dùng scheme: https |
Gitea repo kết nối failed (x509: certificate signed by unknown authority) | repo-server không tin root CA của step-CA (pod không dùng trust store của node) | Thêm root CA: argocd cert add-tls gitea.hoatranlabs.local --from /usr/local/share/ca-certificates/hoatranlabs-root.crt (mục 3.3); --insecure-skip-server-verification chỉ dùng tạm khi thử nghiệm |
| OIDC login redirect loop | Client Secret sai hoặc Redirect URI không khớp | Kiểm tra Authentik Provider config, so sánh với argocd-cm |
SSO báo lỗi x509 khi argocd-server gọi Authentik | argocd-server không tin root CA của step-CA | Kiểm tra rootCA trong oidc.config của argocd-cm (mục 3.4), sau đó restart argocd-server |
| App stuck "OutOfSync" | ArgoCD không pull được từ Gitea | argocd app diff <app> xem chi tiết; check repo server logs |
| Notifications không gửi | Mailu SMTP từ chối, hoặc controller không tin root CA step-CA (log báo x509: certificate signed by unknown authority) | Kiểm tra SMTP credentials, thử telnet mailu.hoatranlabs.local 587 (10.11.35.46) từ trong pod; nếu lỗi x509: kiểm tra biến SSL_CERT_DIR=/app/config/tls trên deployment argocd-notifications-controller (mục 3.6) và root CA có trong argocd cert list --cert-type https |
| Sync loop (liên tục sync) | Manifest có timestamp/random field | Thêm ignoreDifferences trong Application spec |
kubectl apply báo metadata.annotations: Too long khi cài ArgoCD | Apply client-side với CRD ApplicationSet (Argo CD 3.x) | Dùng kubectl apply -n argocd --server-side --force-conflicts -f ... như mục 2.1 |
Checklist triển khai
- K3s cluster (bài 28) đã sẵn sàng: 6 nodes Ready, Traefik, cert-manager OK
- DNS record argocd.hoatranlabs.local → 10.11.65.100 trong Pi-hole
- ArgoCD v3.5.5 cài bằng
--server-side --force-conflicts, namespace argocd tạo thành công, tất cả pods Running - Ingress route và TLS Certificate từ step-CA cấp thành công
-
curl https://argocd.hoatranlabs.local/healthztrả về{"status":"ok"} - ArgoCD CLI login thành công
- Mật khẩu admin đã đổi, initial secret đã xóa
- Gitea repository k8s-manifests kết nối: STATUS=Successful
- Root App of Apps tạo thành công, STATUS=Synced
- Authentik OIDC: login qua browser hoạt động, RBAC đúng role
- Gitea webhook cấu hình, test push → ArgoCD tự sync
- Harbor registry credentials cấu hình trên K3s nodes
- Notifications email: test gửi thành công qua Mailu
- Prometheus ServiceMonitor scrape ArgoCD metrics