---
title: "Argo CD 實戰筆記：從 Helm 安裝到搞定 GitLab SSO"
description: "手把手紀錄如何用 Helm 架設 Argo CD，並串接 GitOps 與 GitLab SSO。告別手動 kubectl，讓 K8s 部署自動化且可追溯。"
canonical_url: "https://blog.markkulab.net/post/argocd-gitops-helm-installation-and-gitlab-sso-setup"
author: "Mark Ku"
author_url: "https://blog.markkulab.net/author/mark-ku"
site: "Mark Ku's Blog"
date_published: "2025-11-20 10:00:00 +0800"
category: "DevOps"
tags: ["kubernetes", "argocd", "gitops", "helm", "gitlab", "devops"]
language: "zh-TW"
license: "CC BY 4.0"
license_url: "https://creativecommons.org/licenses/by/4.0/"
attribution: "轉載或引用請註明作者並附上原文連結"
---

# Argo CD 實戰筆記：從 Helm 安裝到搞定 GitLab SSO

## 為什麼選擇 Argo CD + GitOps？

如果手邊只有一個 K8s 叢集，更新頻率不高，使用 `kubectl apply` 手動部署其實就足夠了。但當架構規模擴大，遇到以下場景時，手動操作就會開始顯得捉襟見肘：

- 需要管理 **10～20 個 K8s 叢集**（包含 Dev/Staging/Prod 等多重環境）
- 頻繁切換 `kubectl context` 容易導致操作失誤
- 手動 Apply 後，難以確認叢集當下的狀態是否與版控一致

這時候，引入 **GitOps + Argo CD** 就能有效解決這些痛點。

其核心邏輯非常直觀：**「將部署的操作自動化，減少人為介入」**。

- **Git 作為單一信任來源 (Source of Truth)**：所有的 YAML、Helm values 都應納入 Git 版本控制。
- **Argo CD 負責自動同步**：它會持續監控 Git 倉庫，一旦程式碼有變更，便自動將叢集狀態同步至預期狀態。
- **快速回滾**：若部署發生問題，只需在 Git 進行 Revert，Argo CD 便會協助切回上一版，確保環境穩定。

這篇筆記主要紀錄建置這套流程的關鍵步驟，包含：使用 Helm 安裝 Argo CD、設定 GitLab SSO，以及如何妥善規劃權限管理。

---

## GitOps 核心概念

這邊不談太多理論，但有一個觀念至關重要。

傳統的部署方式往往缺乏標準化，每個人手動 apply 的內容可能不盡相同，久而久之環境會產生「漂移」 (Drift)，難以追溯。
GitOps 將 Git 視為「標準 SOP」，而 Argo CD 則是執行者。它會確保叢集的實際狀態 (Live State) 永遠與 Git 倉庫中的定義 (Desired State) 保持一致。如果有人手動修改了叢集資源，Argo CD 會偵測到差異並標示為 OutOfSync，甚至可以設定自動修復 (Self-healing) 將其還原。

理解這點後，接下來的設定步驟會更有脈絡。

> （前置作業如 Helm Repo 添加這裡就跳過了，直接進入 SSO 和權限設定的重頭戲）


## 實作開始：搞定認證與安裝

### Step 1：準備 Helm 環境

這步很簡單，先把 Helm 的 repo 加進來，然後把 Argo CD 的預設 values.yaml 匯出來，等等直接改。

```bash
# 新增 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 設定 Application，讓使用者能直接使用 GitLab 帳號登入 Argo CD，便於帳號統一管理。

1. 登入 GitLab → 右上角頭像 → `Settings → Applications`
2. 新增 Application：
  - **Name**：`ArgoCD SSO`
  - **Redirect URI**：`http://<your-node-ip>:32009/api/dex/callback`
  - **Scopes**：勾 `openid`, `read_user`, `email`
3. 儲存後拿到 **Application ID** 和 **Secret**

> ⚠️ 記得 Client ID 和 Secret 不要丟進 Git 倉庫。

![](https://blog.markkulab.net/content/markku/posts/argocd-gitops-helm-installation-and-gitlab-sso-setup/images/attachments/5a1836e9-f936-4e9c-9762-55b5eb67285e.png " =1548x674")

**設定方式有兩種：**

A. 直接寫進 values.yaml（推薦，方便自動化）
B. 安裝完後進 Argo CD UI 補設定（適合臨時調整）

![](https://blog.markkulab.net/content/markku/posts/argocd-gitops-helm-installation-and-gitlab-sso-setup/images/attachments/b8ce9bbd-f83d-4715-96e8-ca016638d3ef.png " =1874x907")


### Step 3：建立 GitLab Group Access Token

Argo CD 需要存取 Git 倉庫的權限來拉取程式碼。
強烈建議**不要使用個人帳號**的 Token，以免人員異動或密碼變更導致正式環境的部署中斷。最佳實踐是申請一個專用的 **Group Access Token**。

1. 到你的 GitLab Group 頁面 → `Settings` → `Access Tokens`。
2. 建立一個 Token：
  - **Name**：取個好認的，例如 `argocd-group-readonly`
  - **Scopes**：勾選 `read_repository` 和 `read_api` 就好，權限越小越安全。
  - **Role**：選 `Reporter`（能讀就好）。
3. **重點**：Token 產生後馬上複製下來，GitLab 只會顯示這一次。


### Step 4：撰寫 values.yaml

這是關鍵的一步。我們會建立一份自定義的 `values.yaml`，將前面取得的 SSO 和 Repo 資訊填入，覆蓋 Helm 的預設設定。

```yaml
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

設定檔都準備好後，直接開工：

```bash
# 安裝 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 將無法進行任何部署操作。

建立 `argocd-projects.yaml`：

```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
```


### 套用設定

```bash
# 套用 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。
2. **Repo 存取（Group Access Token）**：管理程式碼存取權，讓 Argo CD 能讀取 GitLab repo。
3. **Registry（選用）**：管理映像檔去權，若需拉取 private image 需額外設定 Deploy Token。

> 💡 SSO 管「人」、Group Token 管「程式碼」、Registry Token 管「映像檔」。

![](https://blog.markkulab.net/content/markku/posts/argocd-gitops-helm-installation-and-gitlab-sso-setup/images/attachments/b8ce9bbd-f83d-4715-96e8-ca016638d3ef.png " =1874x907")

---


## 實戰範例

### 應用程式狀態總覽

![](https://blog.markkulab.net/content/markku/posts/argocd-gitops-helm-installation-and-gitlab-sso-setup/images/attachments/37293e96-21b9-4734-b8b8-8f657ecd65e6.png)

這張圖是 [Argo CD](https://argo-cd.readthedocs.io/en/stable/) 的 Application 狀態頁，主要觀察以下重點指標：

- **應用程式名稱：** `testapp`
- **APP HEALTH：** ✅ **Healthy**，表示所有資源皆正常運行。
- **SYNC STATUS：** ✅ **Synced to HEAD**，表示 Git 中的設定已完全同步至叢集。
- **LAST SYNC：** ✅ **Sync OK**，最近一次同步成功。
- **Auto sync：** ❌ 未開啟自動同步。

---

### 🌳 應用程式資源架構圖解

用 GitOps 部署的 K8s 資源樹大致長這樣：

1. **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）**

📌 只要右上角顯示為 ✅ 綠色狀態，即代表部署成功。

---


## 常用指令速查
這裡整理了日常維運可能用到的指令，方便快速查閱。

### Helm 相關

```bash
# 安裝 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
```

### K8s 除錯與設定指令

```bash
# 查詢 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 官方文件](https://argo-cd.readthedocs.io/)
- [Argo CD Helm Chart](https://github.com/argoproj/argo-helm)
- [GitLab OAuth 設定](https://docs.gitlab.com/ee/integration/oauth_provider.html)
- [Argo CD 實作範例](https://blog.csdn.net/cr7258/article/details/122028096)
- [GitOps 最佳實踐](https://ithelp.ithome.com.tw/articles/10266761)

---

## 關於本文與作者

本文出自 [Mark Ku's Blog](https://blog.markkulab.net/post/argocd-gitops-helm-installation-and-gitlab-sso-setup)

授權條款： [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) — 轉載或引用請註明作者並附上原文連結

### 關於作者

**[Mark Ku](https://blog.markkulab.net/author/mark-ku)** — Software Solution Provider

- 10+ 年資深軟體工程師，現為 AI 應用 Builder
- 專注大型平台架構設計，從北美電商到AI SaaS訂閱收費系統
- 結合 AI Agent 與自動化，打造高效可演進的產品技術基礎

### 作者開發的免費工具

以下工具皆可免費使用：

- [免費 PDF 簽名工具](https://blog.markkulab.net/tools/pdf-sign): 線上 PDF 簽名工具，瀏覽器內完成手繪、打字、上傳簽名，可拖曳放置、縮放、下載。所有處理都在你的裝置完成，檔案不會上傳。
- [VS Code Refactory](https://blog.markkulab.net/tools/refactory): Refactory 是一款 VS Code 重構擴充套件：34 個重構動作、37 條 code smell 檢查、Code Health 儀表板、18 種語言、534 支測試。懂你的專案慣例：介面放哪、DI 註冊寫在哪、'use client' 該不該加；還會用 git 修改頻率 × 複雜度排出「該先修哪個檔案」，並一鍵把壞味道交給你自己電腦上的 Claude Code 修。免費使用，原始碼不離開你的機器。
- [DB-Kit 資料庫管理工具](https://blog.markkulab.net/tools/db-kit): DB-Kit 是一個用 Tauri + Rust + React 打造的輕量跨平台資料庫管理工具，用單一一致的介面同時管理 MySQL、MariaDB、PostgreSQL、SQL Server、Oracle、SQLite、MongoDB、Redis、Kafka、Elasticsearch 與 RabbitMQ 十一種資料來源：連線密碼以 OS keychain 加密、SSH Tunnel、完整 CRUD、視覺化查詢建構器、多結果集同時顯示、跨連線資料傳輸與比對同步、Excel / CSV 匯入匯出、執行計畫視覺化、ER 圖、排程備份、SQL 壓力測試（p50～p99 延遲百分位）、15 條規則的 SQL 審查、Kafka 訊息瀏覽與監控告警；繁中 / 英文雙語介面，內建 AI 助手（自然語言生成 SQL、AI 審查與調校建議）與命令列工具 dbk。免費開源（MIT），提供 Windows / macOS / Linux 安裝檔。
- [VS Code Super Mermaid](https://blog.markkulab.net/tools/super-mermaid): Super Mermaid 是一款 VS Code 擴充套件：開箱即用的漂亮 Mermaid 圖表，自動上色、即時預覽、滑鼠平移縮放、PNG / SVG 高解析匯出，內建 21 種範本與多種主題。免費開源（MIT）。
- [React Super Mermaid](https://blog.markkulab.net/tools/react-super-mermaid): react-super-mermaid 是一個開源 React 元件庫：一行 <MermaidViewer> 即可渲染漂亮的 Mermaid 圖表，內建 colorful / sketch 主題、平移縮放、圖內搜尋、SVG / PNG 高解析匯出。輕量、SSR 安全、完整 TypeScript 型別。免費開源（MIT）。
- [Jira / Confluence Super Mermaid](https://blog.markkulab.net/tools/jira-super-mermaid): Atlassian Forge app：在 Jira issue 與 Confluence 內文直接寫 Mermaid 語法，畫流程圖、時序圖、狀態機與甘特圖。11 種圖表、SVG / PNG 匯出、明暗主題、完整中日韓文字支援。取得 Runs on Atlassian 資格：圖表存在你自己的站台，app 不呼叫任何第三方服務。免費，即將上架 Atlassian Marketplace。
- [Mermaid 線上預覽](https://blog.markkulab.net/tools/mermaid-preview): 在瀏覽器裡寫 Mermaid、即時看圖，整張圖表壓進網址就能分享。免註冊、不上傳伺服器，相容 mermaid.live 的分享連結。
- [React Intl Phone Number](https://blog.markkulab.net/tools/react-intl-phone-number): react-intl-phone-number 是一個開源 React 元件：framework-agnostic、不依賴 antd，提供 E.164 進出、可搜尋國旗 / 國碼下拉、可配置驗證等級（strict / mobile-strict / loose）、可主題化 CSS 與 i18n，電話邏輯由 google-libphonenumber 驅動。輕量、完整 TypeScript 型別。免費開源（MIT）。
- [Uptime Kuma Cluster](https://blog.markkulab.net/tools/uptime-kuma-cluster): 把單機版 Uptime Kuma 改造成高可用叢集：OpenResty + Lua 智慧負載平衡、MariaDB 共享狀態、健康檢查與自動 Failover，附叢集管理 REST API，一行 Docker Compose 啟動。免費開源（MIT）。
- [特教專案](https://blog.markkulab.net/education): 為特殊教育學生製作的學習教材

### 每日 Podcast

- [科技新鮮事](https://blog.markkulab.net/category/tech-news): 每日精選 AI 與科技趨勢，透過語音摘要快速掌握最新技術動態，涵蓋 AI 應用、軟體架構、DevOps 與工程實戰。 — RSS: https://blog.markkulab.net/feed.xml
- [AI股市蝦聊](https://blog.markkulab.net/category/ai-stock-chat): 每個交易日用 AI 分析台股盤勢，以雙人對話聊當天的盤中觀察與隔日預測。 — RSS: https://blog.markkulab.net/ai-stock-chat/feed.xml

### 電子報

[訂閱電子報](https://blog.markkulab.net/subscribe) — 第一時間收到新文章通知，無垃圾信、隨時可取消訂閱。