Argo-CD-Operator-完全实战指南

1. Argo CD Operator 简介

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

核心思路:

1.1 什么是 OLM(Operator Lifecycle Manager)

OLM 是 Kubernetes 的 Operator 管理框架,负责:

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


2. 环境准备(Kind)

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

配置文件:

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
networking:
  apiServerAddress: "10.10.50.30"
nodes:
- role: control-plane
  extraPortMappings:
  - containerPort: 6443
    hostPort: 6443
    listenAddress: "10.10.50.30"
    protocol: tcp
- role: control-plane
- role: control-plane
- role: worker
- role: worker
- role: worker

创建高可用集群命令:

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 上下文:

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

查看信息:

# 查看集群节点
sudo kubectl get nodes

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

删除集群:

sudo kind delete cluster --name huari-test

3. 安装 OLM(Operator Lifecycle Manager)

官方参考:

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

3.1 安装 OLM 组件

# 先安装 operator-sdk(macOS / Homebrew)
brew install operator-sdk
operator-sdk version

# 再使用 operator-sdk 安装 OLM(官方文档示例)
operator-sdk olm install

Linux(x86_64)安装示例:

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

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

3.2 验证 OLM

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

期望看到:

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

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

判定标准:

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


4. 使用 OLM 安装 Argo CD Operator(统一到 argo 命名空间)

官方参考:

4.1 创建命名空间与 OperatorGroup(使用 AllNamespaces,避免 UnsupportedOperatorGroup)

kubectl create namespace argo

kubectl apply -n argo -f - <<'EOF'
apiVersion: operators.coreos.com/v1
kind: OperatorGroup
metadata:
  name: argocd-operator
spec: {}
EOF

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

4.2 创建 CatalogSource(官方 OLM 步骤)

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

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

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

4.3 创建 Subscription(由 OLM 自动安装 CRD / RBAC / 控制器)

kubectl apply -n argo -f - <<'EOF'
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: argocd-operator
spec:
  channel: alpha
  name: argocd-operator
  source: argocd-catalog
  sourceNamespace: olm
EOF

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

4.4 验证 Operator 安装状态

kubectl get catalogsources -n olm
kubectl get subscriptions -n argo
kubectl get installplans -n argo
kubectl get csv -n argo
kubectl get pods -n argo | grep operator
kubectl get crd | grep argocd

成功判定标准(任一集群重建后都可按此核对):

示例(成功状态):

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

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

5. 创建并托管 Argo CD 实例

官方参考:

5.1 创建最小 ArgoCD CR

kubectl apply -n argo -f - <<'EOF'
apiVersion: argoproj.io/v1beta1
kind: ArgoCD
metadata:
  name: example-argocd
spec: {}
EOF

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

5.2 验证 Argo CD 组件

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

实测通过示例:

kubectl get argocd -n argo
NAME             AGE
example-argocd   3m11s

kubectl get deploy -n argo
NAME                                 READY   UP-TO-DATE   AVAILABLE   AGE
argocd-operator-controller-manager   1/1     1            1           12m
example-argocd-redis                 1/1     1            1           3m14s
example-argocd-repo-server           1/1     1            1           3m14s
example-argocd-server                1/1     1            1           3m14s

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

6. 访问 Argo CD UI 与登录

官方参考:

6.1 端口转发访问

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

访问:

6.2 获取 admin 初始密码

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

7. 参数定制与多实例(官方推荐方式)

官方参考:

7.1 如何定制安装参数

在 Operator 模式下,参数通过 ArgoCD CR 的 spec 定制(不是 Helm values)。

示例(常见参数):

kubectl apply -n argo -f - <<'EOF'
apiVersion: argoproj.io/v1beta1
kind: ArgoCD
metadata:
  name: example-argocd
spec:
  server:
    insecure: true
    resources:
      requests:
        cpu: 250m
        memory: 256Mi
      limits:
        cpu: 500m
        memory: 512Mi
    ingress:
      enabled: true
      ingressClassName: nginx
    host: argocd-a.example.com
    grpc:
      host: argocd-a-grpc.example.com
  ha:
    enabled: false
EOF

查看当前生效配置:

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

7.2 多实例如何区分访问

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

示例(两个实例):

kubectl create namespace argo-a
kubectl create namespace argo-b

kubectl apply -n argo-a -f - <<'EOF'
apiVersion: argoproj.io/v1beta1
kind: ArgoCD
metadata:
  name: argocd-a
spec:
  server:
    host: argocd-a.example.com
EOF

kubectl apply -n argo-b -f - <<'EOF'
apiVersion: argoproj.io/v1beta1
kind: ArgoCD
metadata:
  name: argocd-b
spec:
  server:
    host: argocd-b.example.com
EOF

区分访问方式:

本地端口转发示例:

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

8. 常见问题

8.1 Subscription 一直不就绪

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

重点检查:

8.2 no matches for kind "ArgoCD"

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

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

8.3 Argo CD 组件未拉起

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

8.4 UnsupportedOperatorGroup(OwnNamespace 不支持)

现象(CSV Failed):

Reason: UnsupportedOperatorGroup
Message: OwnNamespace InstallModeType not supported

处理:

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

kubectl delete operatorgroup argocd-operator -n argo --ignore-not-found
kubectl apply -n argo -f - <<'EOF'
apiVersion: operators.coreos.com/v1
kind: OperatorGroup
metadata:
  name: argocd-operator
spec: {}
EOF

kubectl apply -n argo -f - <<'EOF'
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: argocd-operator
spec:
  channel: alpha
  name: argocd-operator
  source: argocd-catalog
  sourceNamespace: olm
  installPlanApproval: Automatic
EOF

9. 卸载

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

# 删除 Operator(OLM)
kubectl delete subscription argocd-operator -n argo
kubectl delete operatorgroup argocd-operator -n argo

# 删除统一命名空间(若无其他业务)
kubectl delete namespace argo

10. 小结

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

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