DEV Community: Jimmy

ArgoCD App of Apps 實作：一個 root Application 管理叢集裡所有的 App

Jimmy — Fri, 16 Oct 2026 04:00:12 +0000

一句話結論：把 ArgoCD 裝好之後，只手動 apply 一個 root Application，讓它掃描 Git 裡的某個目錄；之後要新增、修改、移除任何 App，都只要改 Git，不用再碰 kubectl apply。

遇到的問題

GitOps 的第一步，通常是為每個服務建立一個 ArgoCD Application。

服務少的時候沒問題。服務一多，就變成每新增一個，都要手動 kubectl apply 一份 Application 的 YAML。

這等於在 GitOps 裡留了一個沒被 GitOps 管的缺口：Application 本身不在 Git 的管理範圍內。

解法是 App of Apps：用一個 Application，去管理其他所有 Application。

這篇用最小的例子，從安裝 ArgoCD 開始，走完整個流程。

手把手步驟

步驟一：用 Helm 裝 ArgoCD

前提是手邊已經有一個 Kubernetes 叢集，minikube、kind 或雲端的都可以。

helm repo add argo https://argoproj.github.io/argo-helm
helm repo update

helm upgrade --install argocd argo/argo-cd \
  --namespace argocd --create-namespace \
  --wait --timeout 15m

確認 ArgoCD 起來了：

kubectl -n argocd get pods
kubectl -n argocd rollout status deploy/argocd-server

官方的 Getting Started 是用 kubectl apply 安裝 manifest。這裡改用 Helm，之後想調整參數（資源限制、Ingress 等）比較方便，也方便升級。

步驟二：登入 UI 看一下

最簡單的方式是 port-forward：

kubectl port-forward svc/argocd-server -n argocd 8080:443

然後用瀏覽器打開 https://localhost:8080（憑證是自簽的，瀏覽器會警告）。

帳號是 admin，初始密碼這樣取：

argocd admin initial-password -n argocd

沒有裝 argocd CLI 的話，也可以直接讀 Secret：

kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath='{.data.password}' | base64 -d; echo

官方文件提醒：登入並改完密碼之後，要把 argocd-initial-admin-secret 刪掉。這個 Secret 只是初始用，留著沒有意義。

步驟三：準備 Git repo 的結構

建一個 Git repo，結構長這樣：

gitops/
├── bootstrap/
│   └── root-app.yaml     # 手動 apply 一次
└── apps/                  # root 會掃描這個目錄
    └── guestbook.yaml     # 一個子 Application

兩個目錄要分開：bootstrap/ 放只需要手動套用一次的東西，apps/ 放 root 要持續掃描的東西。

不要把 root 自己放進 apps/，否則會變成 root 在管理自己，行為難以預期，也很難理解。

步驟四：寫一個子 Application

apps/guestbook.yaml，使用 ArgoCD 官方的範例 repo，大家都能拿到：

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps.git
    targetRevision: HEAD
    path: guestbook
  destination:
    server: https://kubernetes.default.svc
    namespace: guestbook
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

幾個欄位值得說明一下。

namespace

Application 這個物件本身預設要放在 argocd namespace。

spec.destination.namespace 才是這個 App 的資源要部署到哪裡。兩個很容易搞混。

finalizer

resources-finalizer.argocd.argoproj.io 的作用是：刪除這個 Application 時，連它部署出來的資源也一起刪掉（預設是前景的 cascading deletion）。

沒有加的話，刪掉 Application 只會移除 ArgoCD 的紀錄，資源還留在叢集裡。

syncPolicy

automated 打開自動同步。prune: true 代表 Git 裡移除的資源，叢集裡也會被刪掉。selfHeal: true 代表有人手動改了叢集內容，ArgoCD 會把它改回 Git 的樣子。

CreateNamespace=true 讓 ArgoCD 在目標 namespace 不存在時自動建立。

步驟五：寫 root Application

bootstrap/root-app.yaml：

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: root
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  source:
    repoURL: https://github.com/<你的帳號>/gitops.git
    targetRevision: main
    path: apps
    directory:
      recurse: true
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

這份 YAML 跟子 Application 長得幾乎一樣，差別有兩個。

path: apps 加 directory.recurse: true

path 指向要掃描的目錄。ArgoCD 預設只讀該目錄第一層的檔案，要往下一層一層讀，要設 recurse: true。

所以之後可以在 apps/ 底下用子資料夾整理，root 一樣讀得到。

destination 的 namespace 是 argocd

因為 root 部署出來的東西就是「Application 這種物件」，而它們預設要在 argocd namespace。

把這個 repo 推到 Git，repoURL 換成自己的。如果是私有 repo，要先在 ArgoCD 設定 repo 的存取憑證。

步驟六：套用 root，看它長出子 App

kubectl apply -f bootstrap/root-app.yaml

這是唯一一次要手動 apply 的東西。

看一下結果：

kubectl get applications -n argocd

預期會看到 root 與 guestbook 兩個，狀態慢慢變成 Synced 與 Healthy：

NAME        SYNC STATUS   HEALTH STATUS
guestbook   Synced        Healthy
root        Synced        Healthy

ArgoCD 預設大約每 3 分鐘輪詢一次 Git，所以 push 之後可能要等一下。急的話，在 UI 上按 Refresh 就會立刻檢查。

步驟七：新增、移除 App，只改 Git

要新增一個 App，在 apps/ 加一個 Application 的 YAML，commit、push。

等下一輪輪詢（或按 Refresh），root 就會偵測到新檔案，建立對應的 Application，新的 App 再各自同步。

要移除，把檔案刪掉再 push。因為 root 有 prune: true，那個 Application 會被刪除，加上子 Application 的 finalizer，它部署的資源也會一起清掉。

全程不需要再對叢集下 kubectl apply。

踩到的坑

1. 刪掉 root，會連帶刪光所有子 App 和它們的資源

root 有加 finalizer，所以刪除它會級聯往下刪：先刪子 Application，子 Application 因為也有 finalizer，再刪它們部署的資源。

換句話說，一個 kubectl delete application root，就能把整個叢集的服務清空。

官方的 Cluster Bootstrapping 文件有專門一節在講這件事。

如果不想要這種風險，可以考慮不給 root 加 finalizer，或是關掉 root 的 prune。取捨是：以後刪除 root 或移除子 Application 時，要自己處理殘留的資源。

2. 子 Application 本身的設定，是由 root 負責同步的

這個坑很隱蔽。假設改了某個子 Application 的設定（例如 plugin 的環境變數、syncOptions），push 之後，如果 root 還沒同步這個改動，子 Application 會繼續用舊的設定渲染，狀態還顯示 Synced，但新開的資源就是沒有出現。

我就是這樣被騙過：看起來一切正常，卻怎麼等都沒有東西。

處理方式是：先確認 root 已經是 Synced，再對子 Application 做一次 hard refresh：

kubectl -n argocd annotate application <名稱> \
  argocd.argoproj.io/refresh=hard --overwrite

hard 的意思是連 manifest 快取都清掉再重新評估。

3. recurse: true 會讀到目錄裡所有的 YAML

root 掃描的目錄裡，只應該放 Application 的 manifest。

如果裡面混了其他 YAML（文件、範例、值檔），ArgoCD 會把它們都當成要部署的資源，可能直接報錯，或是意外建立不該存在的東西。

把「手動套用一次的東西」和「持續掃描的東西」分在不同目錄，就是為了避免這個問題。

為什麼這樣選

官方的 Cluster Bootstrapping 文件，推薦的其實是 ApplicationSet，App of Apps 被列為替代方案。

ApplicationSet 適合「很多個長得很像的 App」或「要部署到很多個叢集」，用 generator 一次產生一堆 Application，不用寫一堆 YAML。

我選 App of Apps 的原因很單純：

一個 App 一個檔案，看檔案就知道它的設定，容易讀。
每個 App 的設定可以各自不同（有的自動同步，有的手動）。
概念簡單，不需要先學 generator 和模板語法。

單一叢集、App 數量不多、每個差異不小的情況，這樣就夠了。要管很多叢集或很多相似的 App，可以直接看 ApplicationSet。

另外有一個官方的安全警告值得記住：App of Apps 是管理員專用的工具。

能在任意 Project 底下建立 Application，等於是管理員等級的權限。所以只有管理員能對 root 所指向的 repo 推送，改動也應該經過審核。

在單機用 k3d 建一個 3 節點 Kubernetes 叢集：從裝 Docker 到資料不會消失的儲存設定

Jimmy — Thu, 15 Oct 2026 08:12:15 +0000

一句話結論：用 k3d 可以在一台機器上用 Docker 容器模擬多節點的 Kubernetes，但要記得兩件事：PV 的資料要掛到主機上，還有 k3s 本來就內建 local-path-provisioner，不要再裝一套。

遇到的問題

需求很單純：一個可以隨便玩、隨便砍、但資料不會跟著消失的 Kubernetes 環境。

放在自己的機器上，不用每個月付雲端的錢。

最省事的選擇其實是 minikube 或 kind。

但我這次要的是多節點，想試 Pod 排程、節點故障這些行為，而且要接近真實的 k3s。

k3d 剛好符合：它把 k3s 包在 Docker 容器裡，一個容器就是一個節點，建一個 3 節點叢集大概一分鐘。

這篇從一台乾淨的 Ubuntu 開始，走完整個建置過程，也會講到中間踩到的幾個坑。

手把手步驟

步驟一：裝 Docker

k3d 的節點是 Docker 容器，所以 Docker 是第一個要裝的。

用 Docker 官方的 apt 套件庫來裝（不是 Ubuntu 預設套件庫裡那個舊版）：

sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

這是照 Docker 官方文件現在寫的方式：金鑰直接存成 docker.asc，套件庫用 .sources 檔。

網路上很多教學還在用比較舊的 gpg --dearmor 加 docker.list 那一套，現在應該也還能用。

新裝的話，建議跟著官方文件走。

然後把自己加進 docker 群組，這樣之後不用每次 sudo：

sudo usermod -aG docker "$USER"

這一步做完要登出再登入一次，群組才會生效。

要注意：docker 群組等於給了該使用者 root 等級的權限，Docker 官方文件有特別提醒。

單人使用的機器可以接受這個取捨；共用的機器請改用官方介紹的 rootless 模式。

步驟二：先設定 Docker 的 log 輪替

這一步很容易被跳過，但建議在建叢集之前就做。

Docker 預設不會限制容器 log 的大小，叢集跑久了，每個節點容器的 log 會一直長大。

sudo tee /etc/docker/daemon.json >/dev/null <<'EOF'
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "5"
  }
}
EOF
sudo systemctl restart docker

意思是：每個容器的 log 最多 5 個檔案，每個最多 10 MB。

如果你的機器上已經有 /etc/docker/daemon.json，不要直接覆蓋，用 jq -s 'add' 把兩份合併。

小提醒：Docker 重啟之後，已經存在的 k3d 叢集不一定會自己起來，要用 k3d cluster start <名稱> 把它叫起來。

步驟三：裝 kubectl、helm、k3d

# kubectl
curl -fsSLo /tmp/kubectl \
  "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -m 0755 /tmp/kubectl /usr/local/bin/kubectl

# helm
curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

# k3d（固定版本，避免哪天自動升級後行為變了）
curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | TAG=v5.8.3 bash

確認都裝好了：

docker --version
kubectl version --client
helm version
k3d version

步驟四：準備一個放 PV 資料的資料夾

這一步先講結論，後面「踩到的坑」會解釋為什麼。

先在主機上建一個資料夾，之後會把它掛進每個節點：

sudo mkdir -p /srv/k3s-storage
sudo chown "$USER":"$USER" /srv/k3s-storage

路徑請換成你自己的。如果你有第二顆比較大的硬碟，放在那顆上會更好。

步驟五：寫叢集設定檔

k3d 支援用一份 YAML 描述整個叢集，比一長串命令列參數好維護，也方便放進 Git。新建 cluster.yaml：

apiVersion: k3d.io/v1alpha5
kind: Simple
metadata:
  name: dev
servers: 1
agents: 2
image: rancher/k3s:v1.31.5-k3s1
ports:
  - port: 80:80
    nodeFilters:
      - loadbalancer
  - port: 443:443
    nodeFilters:
      - loadbalancer
volumes:
  - volume: /srv/k3s-storage:/srv/k3s-storage
    nodeFilters:
      - all
options:
  k3d:
    wait: true
    timeout: "300s"
  kubeconfig:
    updateDefaultKubeconfig: true
    switchCurrentContext: true
  k3s:
    extraArgs:
      - arg: --disable=traefik
        nodeFilters:
          - server:*
  runtime:
    serversMemory: "6GB"
    agentsMemory: "6GB"

逐段說明一下。

節點數量

servers: 1、agents: 2，也就是 1 個控制平面節點加 2 個工作節點，共 3 個。

k3s 版本

image 固定在某個版本。不固定的話，k3d 會用它的預設版本，哪天升級後行為可能就不一樣了。

對外埠

ports 把主機的 80 和 443 轉進叢集，之後放 Ingress 才有入口。

資料夾掛載

volumes 把剛剛那個資料夾掛進所有節點。

Traefik

k3s 預設內建 Traefik 當 Ingress Controller。

如果之後想自己選別的，就用 --disable=traefik 先關掉。沒有特別偏好的話，直接用 Traefik 也完全可以。

記憶體上限

runtime.serversMemory 和 agentsMemory 用來限制每個節點容器的記憶體，這個很容易漏掉。

沒設的話，每個節點容器都會回報「整台主機的記憶體」當自己的上限，三個節點加起來就是三倍的假容量。

排程器以為資源很多，實際一起吃的時候，主機自己會被擠到沒記憶體。

請依機器大小設定，並且留一些給主機本身。

步驟六：建叢集

k3d cluster create --config cluster.yaml

大概一分鐘後完成。確認：

kubectl get nodes

應該會看到 3 個節點，狀態都是 Ready：

NAME               STATUS   ROLES                  AGE   VERSION
k3d-dev-server-0   Ready    control-plane,master   1m    v1.31.5+k3s1
k3d-dev-agent-0    Ready    <none>                 1m    v1.31.5+k3s1
k3d-dev-agent-1    Ready    <none>                 1m    v1.31.5+k3s1

步驟七：把 local-path-provisioner 的資料指到主機上（重點）

k3s 內建一個 local-path-provisioner，PVC 建立後，它會在節點上建一個資料夾存資料。預設路徑是節點容器裡的 /var/lib/rancher/k3s/storage。

而這個路徑沒有掛到主機上。

也就是說，只要節點容器被刪掉重建，PV 的資料就跟著消失了。這對一個「隨時會砍掉重練」的 k3d 叢集來說非常危險。

修法是把它的設定改指向步驟四掛進去的那個資料夾：

kubectl wait --for=condition=available deployment/local-path-provisioner \
  -n kube-system --timeout=120s

kubectl patch configmap local-path-config -n kube-system --type merge \
  -p '{"data":{"config.json":"{\"nodePathMap\":[{\"node\":\"DEFAULT_PATH_FOR_NON_LISTED_NODES\",\"paths\":[\"/srv/k3s-storage\"]}]}"}}'

kubectl rollout restart deployment local-path-provisioner -n kube-system
kubectl rollout status  deployment local-path-provisioner -n kube-system --timeout=60s

再順手把它設成預設的 StorageClass（k3s 通常已經設好了，這行只是確保）：

kubectl patch storageclass local-path \
  -p '{"metadata":{"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

之後建立的 PVC，資料就會落在主機的 /srv/k3s-storage 底下。你可以建一個測試 PVC 驗證一下，再 ls /srv/k3s-storage 看看有沒有出現資料夾。

另一種做法：直接用 k3s 的官方旗標

翻 k3s 文件才發現，官方其實有提供更直接的旗標：在 server 節點加上 --default-local-storage-path，就能指定預設的儲存路徑。放進 cluster.yaml 大概是這樣：

options:
  k3s:
    extraArgs:
      - arg: --default-local-storage-path=/srv/k3s-storage
        nodeFilters:
          - server:*

本篇用的是上面 patch ConfigMap 的做法，這個旗標沒有實際跑過，要用的話請先在臨時叢集上驗證一下。兩種擇一就好，不要同時用。

日常操作

k3d cluster stop  dev    # 停止（資料保留）
k3d cluster start dev    # 啟動
k3d cluster delete dev   # 刪除（掛到主機的資料還在）

踩到的坑

1. 不要再另外裝一套 local-path-provisioner

我當初照著網路上的教學，apply 了官方社群版的 local-path-storage.yaml。

結果新裝的那套一直 CrashLoopBackOff。

後來才搞懂：k3s 本來就內建一套，兩邊的 ClusterRole 與 ClusterRoleBinding 名稱一樣，而且是 cluster 層級的資源。

k3s 的 Addon controller 會一直把它們 reconcile 回內建的版本，新裝那套的 subject namespace 就被蓋掉，沒有權限。

正確做法是上面的步驟七：直接改內建那套的設定，不要再裝新的。

2. PV 資料預設會隨節點容器一起消失

這個我差點中招。

k3d 的節點是容器，容器被刪除重建，容器內的檔案系統就沒了。

一定要用 volumes 把主機資料夾掛進去，再讓 provisioner 寫到那裡。

3. 重啟 Docker 之後要手動把叢集叫起來

改了 daemon.json 重啟 Docker，叢集的容器不一定會自動恢復運作。

記得 k3d cluster start。

為什麼這樣選

k3d 而不是 kind／minikube

要的是多節點加接近真實的 k3s，k3d 在這兩點上最順手。

只要單節點的快速環境的話，minikube 或 kind 都比較簡單。

用設定檔而不是命令列參數

設定檔可以進 Git，之後要重建叢集、跟別人分享，都只要一個檔案。

固定版本

k3d 和 k3s 都固定版本，什麼時候換由自己決定，不是某天自動發生的。

DEV Community: Jimmy

ArgoCD App of Apps 實作：一個 root Application 管理叢集裡所有的 App

遇到的問題

手把手步驟

步驟一：用 Helm 裝 ArgoCD

步驟二：登入 UI 看一下

步驟三：準備 Git repo 的結構

步驟四：寫一個子 Application

步驟五：寫 root Application

步驟六：套用 root，看它長出子 App

步驟七：新增、移除 App，只改 Git

踩到的坑

為什麼這樣選

延伸閱讀

在單機用 k3d 建一個 3 節點 Kubernetes 叢集：從裝 Docker 到資料不會消失的儲存設定

遇到的問題

手把手步驟

步驟一：裝 Docker

步驟二：先設定 Docker 的 log 輪替

步驟三：裝 kubectl、helm、k3d

步驟四：準備一個放 PV 資料的資料夾

步驟五：寫叢集設定檔

步驟六：建叢集

步驟七：把 local-path-provisioner 的資料指到主機上（重點）

另一種做法：直接用 k3s 的官方旗標

日常操作

踩到的坑

為什麼這樣選

延伸閱讀