1772 字

9 分钟

Argo CD Operator 完全实战指南

2026-03-05

Argo

/

Argo CD Operator

Argo CD Operator 完全实战指南#

1. Argo CD Operator 简介#

Argo CD Operator 用于在 Kubernetes 中声明式管理 Argo CD 实例生命周期（安装、升级、配置等）。

核心思路：

先安装 Operator（控制器 + CRD）
再创建 ArgoCD 自定义资源（CR）
由 Operator 自动拉起 Argo CD 组件

1.1 什么是 OLM（Operator Lifecycle Manager）#

OLM 是 Kubernetes 的 Operator 管理框架，负责：

安装 Operator（通过 CatalogSource + Subscription）
处理 Operator 升级（InstallPlan / CSV）
自动落地 Operator 依赖的 CRD/RBAC 等资源

本文采用 Argo CD Operator 官方推荐的 OLM 路线，不使用 Helm 安装 Operator，避免与其他同名社区项目混淆。

2. 环境准备（Kind）#

在开始之前，我们需要一个实验环境。如果你没有现成的Kubernetes集群，可以基于kind搭建测试集群快速创建一个：

配置文件：

1
kind: Cluster
2
apiVersion: kind.x-k8s.io/v1alpha4
3
networking:
4
  apiServerAddress: "10.10.50.30"
5
nodes:
6
- role: control-plane
7
  extraPortMappings:
8
  - containerPort: 6443
9
    hostPort: 6443
10
    listenAddress: "10.10.50.30"
11
    protocol: tcp
12
- role: control-plane
13
- role: control-plane
14
- role: worker
15
- role: worker
16
- role: worker

创建高可用集群命令：

1
sudo kind create cluster --config=huari.yaml --name huari-test --image kindest/node:v1.34.0 --retain; sudo kind export logs --name huari-test

切换 kubectl 上下文：

1
sudo kubectl cluster-info --context kind-huari-test

查看信息：

1
# 查看集群节点
2
sudo kubectl get nodes
3

4
# 查看集群全部的 pod
5
sudo kubectl get pods -A -owide

删除集群：

1
sudo kind delete cluster --name huari-test

3. 安装 OLM（Operator Lifecycle Manager）#

官方参考：

官方文档说明：OLM 是安装 Argo CD Operator 的首选方式。

3.1 安装 OLM 组件#

1
# 先安装 operator-sdk（macOS / Homebrew）
2
brew install operator-sdk
3
operator-sdk version
4

5
# 再使用 operator-sdk 安装 OLM（官方文档示例）
6
operator-sdk olm install

Linux（x86_64）安装示例：

1
curl -LO https://github.com/operator-framework/operator-sdk/releases/latest/download/operator-sdk_linux_amd64
2
chmod +x operator-sdk_linux_amd64
3
sudo mv operator-sdk_linux_amd64 /usr/local/bin/operator-sdk
4
operator-sdk version
5
operator-sdk olm install

如果你不想安装 operator-sdk，可按 OLM QuickStart 中 “Installing OLM in your cluster” 的手工安装方式执行。

3.2 验证 OLM#

1
kubectl get ns | egrep "olm|operators"
2
kubectl get pods -n olm

期望看到：

新增命名空间：olm、operators
olm 命名空间内核心组件为 Running

如果 operator-sdk olm install 最后报 context deadline exceeded，先不要马上重装，优先用下面命令做最终判定：

1
kubectl get deploy -n olm
2
kubectl get pods -n olm -o wide
3
kubectl get apiservice | grep packages.operators.coreos.com

判定标准：

catalog-operator、olm-operator、packageserver 均 Available
v1.packages.operators.coreos.com 为 True

满足上述条件即可视为 OLM 安装成功，继续后续 Operator 安装流程。

4. 使用 OLM 安装 Argo CD Operator（统一到 argo 命名空间）#

官方参考：

4.1 创建命名空间与 OperatorGroup（使用 AllNamespaces，避免 UnsupportedOperatorGroup）#

1
kubectl create namespace argo
2

3
kubectl apply -n argo -f - <<'EOF'
4
apiVersion: operators.coreos.com/v1
5
kind: OperatorGroup
6
metadata:
7
  name: argocd-operator
8
spec: {}
9
EOF

说明：argocd-operator.v0.13.0 在 OLM 下若使用 targetNamespaces: [argo] 可能触发 UnsupportedOperatorGroup (OwnNamespace InstallModeType not supported)。本文改为 AllNamespaces（spec: {}）以与实际可运行行为一致。

4.2 创建 CatalogSource（官方 OLM 步骤）#

1
# 先把官方仓库 clone 到本地（用于取 deploy/catalog_source.yaml）
2
git clone https://github.com/argoproj-labs/argocd-operator.git
3

4
# 使用官方 deploy 清单创建 CatalogSource
5
kubectl create -n olm -f argocd-operator/deploy/catalog_source.yaml

官方示例默认 Operator 安装在 argocd 命名空间。本文统一改为 argo，但流程与资源类型保持一致。

4.3 创建 Subscription（由 OLM 自动安装 CRD / RBAC / 控制器）#

1
kubectl apply -n argo -f - <<'EOF'
2
apiVersion: operators.coreos.com/v1alpha1
3
kind: Subscription
4
metadata:
5
  name: argocd-operator
6
spec:
7
  channel: alpha
8
  name: argocd-operator
9
  source: argocd-catalog
10
  sourceNamespace: olm
11
EOF

说明：在 OLM 流程里，Operator 对应的 CRD、ClusterRole、ClusterRoleBinding 等资源由 CSV/InstallPlan 自动安装，不需要手工逐个 apply。

4.4 验证 Operator 安装状态#

1
kubectl get catalogsources -n olm
2
kubectl get subscriptions -n argo
3
kubectl get installplans -n argo
4
kubectl get csv -n argo
5
kubectl get pods -n argo | grep operator
6
kubectl get crd | grep argocd

成功判定标准（任一集群重建后都可按此核对）：

Subscription 已绑定 argocd-catalog 且无 ResolutionFailed
InstallPlan 存在且 APPROVED=true
CSV 状态为 Succeeded
argocd-operator-controller-manager Pod 为 Running
至少存在 argocds.argoproj.io CRD

示例（成功状态）：

1
kubectl get installplans -n argo
2
NAME            CSV                       APPROVAL    APPROVED
3
install-nmpnk   argocd-operator.v0.13.0   Automatic   true
4

5
kubectl get csv -n argo
6
NAME                      DISPLAY   VERSION   REPLACES                  PHASE
7
argocd-operator.v0.13.0   Argo CD   0.13.0    argocd-operator.v0.12.0   Succeeded

5. 创建并托管 Argo CD 实例#

官方参考：

5.1 创建最小 ArgoCD CR#

1
kubectl apply -n argo -f - <<'EOF'
2
apiVersion: argoproj.io/v1beta1
3
kind: ArgoCD
4
metadata:
5
  name: example-argocd
6
spec: {}
7
EOF

若你的 Operator 版本仅提供 v1alpha1，将 apiVersion 改为 argoproj.io/v1alpha1。

5.2 验证 Argo CD 组件#

1
kubectl get argocd -n argo
2
kubectl get deploy -n argo
3
kubectl get svc -n argo | grep example-argocd-server

实测通过示例：

1
kubectl get argocd -n argo
2
NAME             AGE
3
example-argocd   3m11s
4

5
kubectl get deploy -n argo
6
NAME                                 READY   UP-TO-DATE   AVAILABLE   AGE
7
argocd-operator-controller-manager   1/1     1            1           12m
8
example-argocd-redis                 1/1     1            1           3m14s
9
example-argocd-repo-server           1/1     1            1           3m14s
10
example-argocd-server                1/1     1            1           3m14s
11

12
kubectl get svc -n argo | grep example-argocd-server
13
example-argocd-server          ClusterIP   10.96.175.205   <none>   80/TCP,443/TCP   3m20s
14
example-argocd-server-metrics  ClusterIP   10.96.248.50    <none>   8083/TCP         3m20s

6. 访问 Argo CD UI 与登录#

官方参考：

Argo CD Operator - Usage / Basics（Server API & UI）

6.1 端口转发访问#

1
kubectl -n argo port-forward service/example-argocd-server 8443:443 --address 0.0.0.0

访问：

https://127.0.0.1:8443

6.2 获取 admin 初始密码#

1
kubectl -n argo get secret example-argocd-cluster -o jsonpath='{.data.admin\.password}' | base64 -d

7. 参数定制与多实例（官方推荐方式）#

官方参考：

7.1 如何定制安装参数#

在 Operator 模式下，参数通过 ArgoCD CR 的 spec 定制（不是 Helm values）。

示例（常见参数）：

1
kubectl apply -n argo -f - <<'EOF'
2
apiVersion: argoproj.io/v1beta1
3
kind: ArgoCD
4
metadata:
5
  name: example-argocd
6
spec:
7
  server:
8
    insecure: true
9
    resources:
10
      requests:
11
        cpu: 250m
12
        memory: 256Mi
13
      limits:
14
        cpu: 500m
15
        memory: 512Mi
16
    ingress:
17
      enabled: true
18
      ingressClassName: nginx
19
    host: argocd-a.example.com
20
    grpc:
21
      host: argocd-a-grpc.example.com
22
  ha:
23
    enabled: false
24
EOF

查看当前生效配置：

1
kubectl get argocd example-argocd -n argo -o yaml

7.2 多实例如何区分访问#

官方建议：同一命名空间只放一个 Argo CD 实例，多实例请使用不同命名空间。

示例（两个实例）：

1
kubectl create namespace argo-a
2
kubectl create namespace argo-b
3

4
kubectl apply -n argo-a -f - <<'EOF'
5
apiVersion: argoproj.io/v1beta1
6
kind: ArgoCD
7
metadata:
8
  name: argocd-a
9
spec:
10
  server:
11
    host: argocd-a.example.com
12
EOF
13

14
kubectl apply -n argo-b -f - <<'EOF'
15
apiVersion: argoproj.io/v1beta1
16
kind: ArgoCD
17
metadata:
18
  name: argocd-b
19
spec:
20
  server:
21
    host: argocd-b.example.com
22
EOF

区分访问方式：

argo-a：svc/argocd-a-server
argo-b：svc/argocd-b-server
或通过不同 ingress host（如 argocd-a.example.com / argocd-b.example.com）

本地端口转发示例：

1
kubectl -n argo-a port-forward svc/argocd-a-server 8443:443 --address 0.0.0.0
2
kubectl -n argo-b port-forward svc/argocd-b-server 9443:443 --address 0.0.0.0

8. 常见问题#

8.1 Subscription 一直不就绪#

1
kubectl describe subscription argocd-operator -n argo
2
kubectl get catalogsources -n olm
3
kubectl get pods -n olm

重点检查：

argocd-catalog 是否存在且状态正常
OLM 核心组件 Pod 是否 Running

8.2 `no matches for kind "ArgoCD"`#

原因：CRD 还没由 OLM 安装完成。
处理：

1
kubectl get csv -n argo
2
kubectl get crd | grep argocds.argoproj.io

8.3 Argo CD 组件未拉起#

1
kubectl describe argocd example-argocd -n argo
2
kubectl get events -n argo --sort-by=.lastTimestamp | tail -n 30
3
kubectl logs -n argo deploy/argocd-operator-controller-manager

8.4 `UnsupportedOperatorGroup`（OwnNamespace 不支持）#

现象（CSV Failed）：

1
Reason: UnsupportedOperatorGroup
2
Message: OwnNamespace InstallModeType not supported

处理：

1
kubectl delete subscription argocd-operator -n argo --ignore-not-found
2
kubectl delete csv argocd-operator.v0.13.0 -n argo --ignore-not-found
3
kubectl delete installplan --all -n argo
4

5
kubectl delete operatorgroup argocd-operator -n argo --ignore-not-found
6
kubectl apply -n argo -f - <<'EOF'
7
apiVersion: operators.coreos.com/v1
8
kind: OperatorGroup
9
metadata:
10
  name: argocd-operator
11
spec: {}
12
EOF
13

14
kubectl apply -n argo -f - <<'EOF'
15
apiVersion: operators.coreos.com/v1alpha1
16
kind: Subscription
17
metadata:
18
  name: argocd-operator
19
spec:
20
  channel: alpha
21
  name: argocd-operator
22
  source: argocd-catalog
23
  sourceNamespace: olm
24
  installPlanApproval: Automatic
25
EOF

9. 卸载#

1
# 删除 Argo CD 实例
2
kubectl delete argocd example-argocd -n argo
3

4
# 删除 Operator（OLM）
5
kubectl delete subscription argocd-operator -n argo
6
kubectl delete operatorgroup argocd-operator -n argo
7

8
# 删除统一命名空间（若无其他业务）
9
kubectl delete namespace argo

10. 小结#

这套方案在 Kind 中完成了 Argo CD Operator 的完整闭环：

OLM 安装并托管 Operator 生命周期
Operator 自动安装并维护 CRD/RBAC/控制器资源
通过 ArgoCD CR 声明式创建 Argo CD 实例
全文资源统一到 argo 命名空间，便于与你现有 Events 文档保持一致

如果你下一步要落生产，建议继续补充：

Argo CD 高可用配置（HA）
细粒度 RBAC 与 SSO
Operator 升级与回滚流程
基于 GitOps 的 ArgoCD CR 管理策略

Argo CD Operator 完全实战指南

https://hua-ri.cn/posts/argo-cd-operator-完全实战指南/

作者

花日

发布于

2026-03-05

许可协议

CC BY-NC-SA 4.0

部分信息可能已经过时

Argo Events 完全实战指南

Argo Workflows 完全实战指南

花日の博客

Argo CD Operator 完全实战指南#

1. Argo CD Operator 简介#

1.1 什么是 OLM（Operator Lifecycle Manager）#

2. 环境准备（Kind）#

3. 安装 OLM（Operator Lifecycle Manager）#

3.1 安装 OLM 组件#

3.2 验证 OLM#

4. 使用 OLM 安装 Argo CD Operator（统一到 argo 命名空间）#

4.1 创建命名空间与 OperatorGroup（使用 AllNamespaces，避免 UnsupportedOperatorGroup）#

4.2 创建 CatalogSource（官方 OLM 步骤）#

4.3 创建 Subscription（由 OLM 自动安装 CRD / RBAC / 控制器）#

4.4 验证 Operator 安装状态#

5. 创建并托管 Argo CD 实例#

5.1 创建最小 ArgoCD CR#

5.2 验证 Argo CD 组件#

6. 访问 Argo CD UI 与登录#

6.1 端口转发访问#

6.2 获取 admin 初始密码#

7. 参数定制与多实例（官方推荐方式）#

7.1 如何定制安装参数#

7.2 多实例如何区分访问#

8. 常见问题#

8.1 Subscription 一直不就绪#

8.2 no matches for kind "ArgoCD"#

8.3 Argo CD 组件未拉起#

8.4 UnsupportedOperatorGroup（OwnNamespace 不支持）#

9. 卸载#

10. 小结#

8.2 `no matches for kind "ArgoCD"`#

8.4 `UnsupportedOperatorGroup`（OwnNamespace 不支持）#