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搭建测试集群快速创建一个:
配置文件:
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)
官方参考:
- Argo CD Operator - Install / Getting Started
- Argo CD Operator - Install / OLM
- Operator SDK Installation
- OLM QuickStart
官方文档说明: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
期望看到:
- 新增命名空间:
olm、operators olm命名空间内核心组件为Running
如果 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
判定标准:
catalog-operator、olm-operator、packageserver均Availablev1.packages.operators.coreos.com为True
满足上述条件即可视为 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
成功判定标准(任一集群重建后都可按此核对):
Subscription已绑定argocd-catalog且无ResolutionFailedInstallPlan存在且APPROVED=trueCSV状态为Succeededargocd-operator-controller-managerPod 为Running- 至少存在
argocds.argoproj.ioCRD
示例(成功状态):
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. 参数定制与多实例(官方推荐方式)
官方参考:
- Argo CD Operator - Usage / Basics
- Argo CD Operator - Reference / ArgoCD
- Argo CD Operator - Usage / Ingress
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
区分访问方式:
argo-a:svc/argocd-a-serverargo-b:svc/argocd-b-server- 或通过不同 ingress host(如
argocd-a.example.com/argocd-b.example.com)
本地端口转发示例:
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
重点检查:
argocd-catalog是否存在且状态正常- OLM 核心组件 Pod 是否 Running
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 的完整闭环:
- OLM 安装并托管 Operator 生命周期
- Operator 自动安装并维护 CRD/RBAC/控制器资源
- 通过
ArgoCDCR 声明式创建 Argo CD 实例 - 全文资源统一到
argo命名空间,便于与你现有 Events 文档保持一致
如果你下一步要落生产,建议继续补充:
- Argo CD 高可用配置(HA)
- 细粒度 RBAC 与 SSO
- Operator 升级与回滚流程
- 基于 GitOps 的 ArgoCD CR 管理策略