前言
如果你現在手上有 10～20 個 Kubernetes 集群 要顧，還在那邊每一個用 kubectl 手動切 context、apply YAML，其實滿折騰的。
有點像你有 20 支手機，要裝同一個 App，結果你一支一支打開商店搜尋、下載、登入——某一天一定會漏裝、裝錯，或是少改一個設定。
Argo CD 搭配 GitOps 就是在解決這種「人手操作一定會出包」的場景。缺點是，它的學習曲線的確比單純用 kubectl 陡一點，你要先理解：
- GitOps 在講的「宣告式」跟「唯一真相來源」到底是什麼
- Argo CD 裡的 Application、Project、Sync 這些東西在玩什麼
- Helm、OAuth、Registry、RBAC 這些元件要怎麼串在一起
但一旦這些拼圖拼起來，多叢集、多環境的日常維運真的會輕鬆非常多。
這篇文章會帶你一步一步做完三件事：
- 先搞清楚 Argo CD 在整個 GitOps 架構裡是誰、在幹嘛
- 用 Helm 把 Argo CD 安裝起來、必要設定補好
- 把 GitLab SSO 串進來，讓登入、權限都用同一套帳號系統管
核心概念
什麼是 GitOps？
先把 GitOps 講白話一點，它其實就是一句話：
「把基礎設施當程式碼管，然後一切以 Git 為準。」
細拆會長這樣：
- Git 是唯一真相來源：所有 Kubernetes 設定檔（YAML、Helm values…）都丟在 Git 裡，Git 就是「環境該長什麼樣子」的標準答案。
- 自動同步：不是你自己去下
kubectl apply，而是系統自動去看 Git，幫你把集群調整成那個狀態。 - 版本可回溯：誰改了什麼、什麼時候改，只要有 commit 記錄就查得到，真的炸掉了也可以直接回滾。
可以把它想成：
以前大家在廚房裡都憑感覺煮，每個人心中都有自己的版本，但有了ArgoCD，大家依據食譜做菜
安裝相關環境
Step 1：準備 Helm 環境
在開始安裝之前，我們需要先把 Helm 的「軟體來源」設定好。就像你要裝 App 前要先確認應用商店能連上一樣，這裡要讓 Helm 知道去哪裡抓 Argo CD 的安裝包，然後把預設設定檔匯出來方便我們後續修改。
加入 Argo CD 的 Helm repository 並匯出預設設定檔：
# 新增 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 設定 SSO 整合：
- 登入 GitLab → 點選右上角頭像 →
Settings → Applications - 點選 New Application 並填寫：
- Name：
ArgoCD SSO - Redirect URI：
http://<your-node-ip>:32009/api/dex/callback - Scopes：勾選
openid,read_user,email
- Name：
- 儲存後取得 Application ID 和 Secret
⚠️ 請妥善保存 Client ID 和 Secret，不要提交到 Git 倉庫中。
兩種設定方式：
方案 A：透過 values.yaml 設定（建議）
- 在後續 Step 4 中，將 Client ID 和 Secret 寫入
values.yaml的dex.config區塊 - 安裝時一次到位，適合自動化部署
方案 B：透過 UI 設定
- 安裝後登入 Argo CD UI →
Settings → SSO / OAuth - 選擇 GitLab 並填寫 Client ID、Secret、Redirect URI
- 適合事後補強或調整設定
Step 3：建立 GitLab Group Access Token
為了讓 Argo CD 能夠自動拉取 GitLab 上的程式碼和 Helm Chart，我們需要給它一把「讀取權限鑰匙」。Group Access Token 就是這把鑰匙，它可以讓 Argo CD 存取整個 GitLab Group 底下的所有專案，而不用每個 repo 都單獨設定一次。
- 前往 GitLab Group →
Settings → Access Tokens - 建立新 Token：
- Name：
argocd-group-readonly - Scopes：勾選
read_repository和read_api - Role：選擇
Reporter
- Name：
- 儲存後複製 Token（只會顯示一次）
Step 4：配置 values.yaml
現在要把前面準備好的「通行證」（OAuth）和「讀取鑰匙」（Group Token）寫進 Argo CD 的設定檔裡。這個 values.yaml 就像是 Argo CD 的「身分證+通訊錄」，告訴它自己的對外網址是什麼、要怎麼跟 GitLab 溝通、可以存取哪些 repo。
編輯 values.yaml，整合所有設定：
configs:
cm:
# Argo CD 對外 URL
url: http://<your-node-ip>:32009
# GitLab 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>
redirectURI: http://<your-node-ip>:32009/api/dex/callback
# GitLab Repository 認證（使用 Group Access Token）
credentialTemplates:
gitlab-group-token:
url: https://gitlab.example.com
username: oauth2
password: <your-gitlab-group-access-token>
# 預先註冊的 Repository
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 網路設定
server:
service:
type: NodePort
nodePortHttp: 32009
nodePortHttps: 32010
# 允許 HTTP（僅開發環境使用）
extraArgs:
- --insecure
💡 生產環境建議：使用 Ingress + TLS 取代 NodePort，並移除
--insecure參數。
Step 5：執行安裝
設定檔準備好了，現在可以正式把 Argo CD 「蓋」到 Kubernetes 集群上。這個過程會建立所有必要的 Pod、Service、ConfigMap 等等，然後等它們全部啟動完成。就像蓋房子一樣，材料備齊了就開始施工，最後驗收確認能住人。
套用設定檔並安裝 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 安裝好了，但現在它還不知道「可以管哪些資源」、「可以部署到哪些地方」。AppProject 就像是一份「授權清單」，明確定義 Argo CD 可以碰哪些 Kubernetes 資源、可以連到哪些集群、可以存取哪些 Git repo。沒有這個授權，Argo CD 就會因為權限不足而無法正常工作。
安裝完成後，需要配置 AppProject 來管理應用程式的權限範圍。
建立 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 整合涉及三層權限管理：
1. SSO 登入（GitLab OAuth）
- 控制使用者身分驗證與授權
- 決定誰可以存取 Argo CD UI 及可見的 Application 範圍
- 本文已在 Step 4 的
values.yaml中完成設定
2. Repository 存取（Group Access Token）
- 讓 Argo CD 讀取 GitLab 倉庫的程式碼與 Helm Chart
- 採用 Group Access Token 統一管理整個 Group 的權限
- 已在 Step 4 的
credentialTemplates中完成設定
3. Container Registry（選用）
- 若使用 GitLab Container Registry 拉取映像檔，需額外設定
- 可使用 Deploy Token 建立
imagePullSecrets
💡 簡單記憶：SSO 管「人」，Group Token 管「程式碼」，Registry Token 管「映像檔」。
實戰範例
應用程式狀態總覽
圖表說明
這張圖片是 Argo CD 的應用程式狀態畫面，用來管理 Kubernetes 應用程式的部署狀態：
- 應用程式名稱：
testapp - APP HEALTH（健康狀態）： ✅ Healthy → 代表應用程式目前的所有資源都運作正常。
- SYNC STATUS（同步狀態）： ✅ Synced to HEAD (d227ef5) → 表示 Git 倉庫裡的設定檔已成功同步到叢集，沒有偏差。
- LAST SYNC： ✅ Sync OK → 最近一次同步成功，是在
18 hours ago（18 小時前）由mark.ku完成的。 → 提交備註為update config。 - Auto sync： ❌ 未啟用自動同步（Auto sync is not enabled）
🌳 應用程式資源架構圖解
這是以 GitOps 模式部署的 Kubernetes 應用資源樹狀圖：
- testapp（應用程式）
- 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 密碼後，請立即登入並修改密碼以確保安全。
總結
透過本文，您已經完成：
- ✅ 理解 GitOps 與 Argo CD 的核心概念
- ✅ 使用 Helm 完整安裝與配置 Argo CD
- ✅ 整合 GitLab SSO 實現安全的身分驗證
- ✅ 使用 Group Access Token 管理倉庫存取權限
- ✅ 設定 RBAC 與 AppProject 控制資源權限
下一步建議：
- 建立您的第一個 Application，實際體驗 GitOps 工作流程
- 啟用自動同步功能，實現完全自動化部署
- 整合 CI/CD Pipeline，建立完整的 DevOps 流程
- 在生產環境中配置 Ingress + TLS，提升安全性
參考資料
Related Posts
