聊聊為什麼要用 Argo CD + GitOps？
先說個大實話，如果你手邊只有一個 K8s 叢集，偶爾版更一次，那其實 kubectl apply 加減用也沒什麼問題。但如果你跟我一樣遇到這種場景：
- 公司長出了 10～20 個 K8s 叢集（Dev/Staging/Prod 分得亂七八糟）
- 每次版更都要切換
kubectl context，切到頭暈 - 手動 Apply 完，根本不知道現在環境跟版控裡的 YAML 到底還一不一樣
這時候，GitOps + Argo CD 就是救星了。
簡單來說，它的邏輯就是：「別再讓人去動叢集，讓機器人去動」。
- Git 是老大：所有 YAML、Helm values 全部丟進 Git，它就是唯一真理（Source of Truth）。
- Argo CD 是監工：它會盯著 Git 看，一旦你推了 code，它就自動把叢集變成你要的樣子。
- 回滾超快：出包了？Git Revert 一下，Argo CD 馬上幫你切回上一版。
這篇筆記主要紀錄我最近把這套流程架起來的步驟，包含：用 Helm 安裝 Argo CD、最麻煩的 GitLab SSO 串接，以及權限怎麼管才不會出事。
觀念對齊：GitOps 到底在幹嘛？
雖然不想講太多理論，但有個觀念一定要通。
以前我們是「煮大鍋飯」，每個人隨興加料（手動 apply），最後沒人記得這鍋湯裡到底放了什麼。 GitOps 就像是「標準SOP食譜」，Argo CD 是那個死板的廚師長，他會嚴格執行食譜（Git Repo）。如果有人偷偷往湯裡加鹽（手動修改 Cluster），Argo CD 會發現「欸？跟食譜不一樣」，然後強制把它改回來（Self-healing）。
搞懂這個，後面的設定才合理。
（前置作業如 Helm Repo 添加這裡就跳過了，直接進入 SSO 和權限設定的重頭戲）
實作開始：搞定認證與安裝
Step 1：準備 Helm 環境
這步很簡單，先把 Helm 的 repo 加進來，然後把 Argo CD 的預設 values.yaml 匯出來，等等直接改。
# 新增 Helm repository helm repo add argo https://argoproj.github.io/argo-helm helm repo update # 匯出預設 values 供修改使用 helm show values argo/argo-cd --version 8.3.2 > values.yaml
Step 2：建立 GitLab OAuth Application
這步是要讓 Argo CD 跟 GitLab 建立信任關係，等於在 GitLab 幫 Argo CD 辦一張「通行證」，以後大家都能用 GitLab 帳號登入 Argo CD。
- 登入 GitLab → 右上角頭像 →
Settings → Applications - 新增 Application：
- Name：
ArgoCD SSO - Redirect URI：
http://<your-node-ip>:32009/api/dex/callback - Scopes：勾
openid,read_user,email
- 儲存後拿到 Application ID 和 Secret
⚠️ 記得 Client ID 和 Secret 不要丟進 Git 倉庫。
設定方式有兩種：
A. 直接寫進 values.yaml（推薦，方便自動化） B. 安裝完後進 Argo CD UI 補設定（適合臨時調整）
Step 3：建立 GitLab Group Access Token
Argo CD 要去拉 Git 裡的 Code，總得給它一把鑰匙。 這裡強烈建議不要用你個人的帳號，不然哪天你離職或改密碼，整個 Production 部署就掛了。最好的方式是用 Group Access Token。
- 到你的 GitLab Group 頁面 →
Settings→Access Tokens。 - 建立一個 Token：
- Name：取個好認的，例如
argocd-group-readonly - Scopes：勾選
read_repository和read_api就好，權限越小越安全。 - Role：選
Reporter（能讀就好）。
- 重點：Token 產生後馬上複製下來，GitLab 只會顯示這一次。
Step 4：撰寫 values.yaml
這是最關鍵的一步。我們不直接用 Helm 的預設設定，而是要寫一份自己的 values.yaml，把 SSO 和 Repo 的資訊灌進去。這份檔案就是 Argo CD 的身分證。
configs:
cm:
# 這裡填 Argo CD 的入口網址，SSO callback 會用到
url: http://<your-node-ip>:32009
# 這是最容易卡關的地方：Dex (SSO) 設定
dex.config: |
connectors:
- type: gitlab
id: gitlab
name: GitLab
config:
baseURL: https://gitlab.example.com
clientID: <your-gitlab-oauth-client-id>
clientSecret: <your-gitlab-oauth-client-secret>
# 記得要去 GitLab Application 設定裡把這個 Callback URL 填對
redirectURI: http://<your-node-ip>:32009/api/dex/callback
# 這裡把剛剛申請的 Token 填進去，讓 Argo CD 認得你的 GitLab
credentialTemplates:
gitlab-group-token:
url: https://gitlab.example.com
username: oauth2 # 固定寫 oauth2 即可
password: <your-gitlab-group-access-token>
# 預先註冊 Repo，省得之後在 UI 一個一個加
repositories:
kong-api-gateway:
url: https://gitlab.example.com/your-group/kong-api-gateway.git
type: git
argocd-deployment:
url: https://gitlab.example.com/your-group/argocd-deployment.git
type: git
# Server 網路設定 (Lab 環境偷懶用 NodePort，正式環境請上 Ingress)
server:
service:
type: NodePort
nodePortHttp: 32009
nodePortHttps: 32010
# 開發環境允許 HTTP，不然會一直跳憑證錯誤
extraArgs:
- --insecure
💡 生產環境建議：Ingress + TLS 取代 NodePort，並移除
--insecure。
Step 5：安裝 Argo CD
設定檔都準備好後，直接開工：
# 安裝 Argo CD
helm upgrade --install homelab-argo argo/argo-cd \
--version 8.3.2 \
-f values.yaml \
-n argocd --create-namespace
# 等 Pod 跑起來
kubectl wait --for=condition=ready pod \
-l app.kubernetes.io/name=argocd-server \
-n argocd --timeout=300s
# 拿初始 admin 密碼
kubectl -n argocd get secret argocd-initial-admin-secret \
-o jsonpath="{.data.password}" | base64 -d
第一次登入記得馬上改 admin 密碼。
權限管理
Step 6：設定 RBAC 跟 AppProject
Argo CD 裝好只是第一步，還要告訴它「你可以管哪些資源、可以 deploy 到哪些地方」。AppProject 就像是授權清單，沒設好權限，Argo CD 什麼都不能做。
建立 argocd-projects.yaml：
apiVersion: v1
kind: List
items:
# Default Project - 基本權限
- apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
name: default
namespace: argocd
spec:
# 允許所有來源 repo
sourceRepos:
- '*'
# 允許部署到所有叢集與 namespace
destinations:
- namespace: '*'
server: '*'
# 允許操作集群級資源
clusterResourceWhitelist:
- group: '*'
kind: '*'
# 允許操作命名空間級資源
namespaceResourceWhitelist:
- group: '*'
kind: '*'
# 自訂 Project - 依需求調整
- apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
name: your-project
namespace: argocd
spec:
description: 你的專案描述
sourceRepos:
- 'https://gitlab.example.com/your-group/*'
destinations:
- namespace: '*'
server: https://kubernetes.default.svc
# 集群級資源白名單
clusterResourceWhitelist:
- group: ''
kind: Namespace
- group: 'rbac.authorization.k8s.io'
kind: ClusterRole
- group: 'rbac.authorization.k8s.io'
kind: ClusterRoleBinding
- group: 'apiextensions.k8s.io'
kind: CustomResourceDefinition
# 命名空間級資源白名單
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: 'networking.k8s.io'
kind: Ingress
# Argo CD Controller 額外的 RBAC 權限（支援 metrics-server 等）
- apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: argocd-application-controller-auth-delegator
labels:
app.kubernetes.io/component: application-controller
app.kubernetes.io/name: argocd-application-controller
app.kubernetes.io/part-of: argocd
rules:
# Auth delegation for metrics-server
- apiGroups: ["authentication.k8s.io"]
resources: ["tokenreviews"]
verbs: ["create"]
- apiGroups: ["authorization.k8s.io"]
resources: ["subjectaccessreviews"]
verbs: ["create"]
# API Services management
- apiGroups: ["apiregistration.k8s.io"]
resources: ["apiservices"]
verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
- apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: argocd-application-controller-auth-delegator
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: argocd-application-controller-auth-delegator
subjects:
- kind: ServiceAccount
name: argocd-application-controller
namespace: argocd
套用設定
# 套用 AppProject 跟 RBAC 設定 kubectl apply -f argocd-projects.yaml -n argocd # 看 Project 有沒有建起來 kubectl get appprojects -n argocd # RBAC 權限也查一下 kubectl get clusterrole | grep argocd kubectl get clusterrolebinding | grep argocd
權限結構小抄
Argo CD 跟 GitLab 整合，權限分三層：
- SSO 登入（GitLab OAuth）：管誰能進 Argo CD UI
- Repo 存取（Group Access Token）：管 Argo CD 能讀哪些 GitLab repo
- Registry（選用）：拉 image 要額外設 Deploy Token
💡 SSO 管「人」、Group Token 管「程式碼」、Registry Token 管「映像檔」。
實戰範例
應用程式狀態總覽
這張圖是 Argo CD 的 Application 狀態頁，主要看幾個重點：
- 應用程式名稱：
testapp - APP HEALTH： ✅ Healthy，全部資源都正常
- SYNC STATUS： ✅ Synced to HEAD，Git 設定已同步到叢集
- LAST SYNC： ✅ Sync OK，最近一次同步成功
- Auto sync： ❌ 沒開自動同步
🌳 應用程式資源架構圖解
用 GitOps 部署的 K8s 資源樹大致長這樣：
- testapp（Application）
- nginx-content（ConfigMap）
- test-app（Namespace）
- nginx-test-service（Service）
- nginx-test（Deployment）
- nginx-test-554867cd4b（ReplicaSet）
- nginx-test-554867cd4b-65gtp（Pod）
- nginx-test-554867cd4b-xgs9x（Pod）
- nginx-test-554867cd4b（ReplicaSet）
📌 只要右上角有 ✅ 就是部署成功。
常用指令小抄
Helm 相關
# 安裝 Helm（Windows） choco install kubernetes-helm # 安裝/升級 Argo CD helm upgrade --install argocd argo/argo-cd \ --namespace argocd --create-namespace \ -f values.yaml # 匯出目前設定 helm get values argocd -n argocd -o yaml > current-values.yaml
Kubernetes 相關
# 查詢 Argo CD Service
kubectl get svc argocd-server -n argocd
# Service 改成 NodePort
kubectl patch svc argocd-server -n argocd -p '{
"spec": {
"type": "NodePort",
"ports": [
{
"port": 80,
"targetPort": 8080,
"nodePort": 32009
}
]
}
}'
# 拿初始 admin 密碼
kubectl -n argocd get secret argocd-initial-admin-secret \
-o jsonpath="{.data.password}" | base64 -d
# 匯出 AppProject 設定
kubectl get appprojects -n argocd -o yaml > argocd-projects.yaml
⚠️ admin 密碼拿到後，記得馬上改掉。
總結
這篇筆記帶你從零到一把 Argo CD + GitOps + GitLab SSO 全部串起來，重點流程都跑過一遍。
- GitOps/Argo CD 觀念對齊
- 用 Helm 安裝、配置 Argo CD
- GitLab SSO 串接，安全登入
- Group Access Token 管理 repo 權限
- RBAC/AppProject 控制資源範圍
下一步建議：
- 建第一個 Application，實際跑跑看
- 開啟自動同步，體驗全自動部署
- 整合 CI/CD Pipeline，DevOps 一條龍
- 生產環境記得用 Ingress + TLS
參考資料
Related Posts
