Argo-Events-完全实战指南
1. Argo Events 简介
Argo Events 是 Argo 生态中的事件驱动框架,用于监听外部或内部事件(Webhook、Git、消息队列、定时器等),并通过 Sensor 触发 Kubernetes 资源创建、Argo Workflows 执行等动作。
核心组件:
- EventSource:负责接收事件
- EventBus:负责事件传输(通常基于 NATS)
- Sensor:负责消费事件并触发动作
2. 环境准备
2.1 搭建 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. ArgoCD 部署
参考ArgoCD在Kind集群的部署来在kind集群安装ArgoCD。
3.1 部署 ArgoCD
# 更新helm repo
helm repo add argo https://argoproj.github.io/argo-helm
helm repo update
# 部署argocd
helm upgrade --install argocd argo/argo-cd \
--version 7.3.5 \
--namespace argo \
--create-namespace
如果网络存在问题,也可以从本地chart进行安装:
helm pull argo/argo-cd --version 7.3.5
helm upgrade --install argocd ./argo-cd-7.3.5.tgz \
--namespace argo \
--create-namespace
3.2 暴露 ArgoCD 服务
# 使用端口转发访问 UI
kubectl port-forward svc/argocd-server -n argo 8080:443 --address 0.0.0.0
3.3 获取初始密码
# 获取初始管理员密码
kubectl -n argo get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d
4. Argo Workflows 部署
# 添加 Argo Helm 仓库
helm repo add argo https://argoproj.github.io/argo-helm
helm repo update
# 安装 Argo Workflows(测试环境配置)
helm upgrade --install argo-workflows argo/argo-workflows \
--version 0.47.4 \
--namespace argo \
--create-namespace \
--set server.secure=false \
--set server.extraArgs[0]="--auth-mode=server" \
--set workflow.serviceAccount.create=true \
--set workflow.serviceAccount.name=argo-workflow \
--set workflow.rbac.create=true \
--set 'workflow.rbac.rules[0].apiGroups[0]=' \
--set 'workflow.rbac.rules[0].apiGroups[1]=apps' \
--set 'workflow.rbac.rules[0].resources[0]=*' \
--set 'workflow.rbac.rules[0].verbs[0]=*'
验证:
kubectl get pods -n argo -w
5. 使用 Helm 部署 Argo Events
官方参考:
5.1 安装 Argo Events
# 添加仓库
helm repo add argo https://argoproj.github.io/argo-helm
helm repo update
# 统一使用 Helm 安装,并显式开启 CRDs/RBAC 相关项
helm upgrade --install argo-events argo/argo-events \
--namespace argo \
--create-namespace \
--set installCRDs=true \
--set crds.install=true \
--set rbac.create=true
说明:不同 chart 版本字段可能略有差异,这里同时设置
installCRDs与crds.install,以覆盖常见版本写法;RBAC 由 Helm 安装阶段直接创建。
5.2 验证安装
kubectl get pods -n argo
kubectl get crd | grep argoproj.io
6. 部署 EventBus / EventSource / Sensor(按官方 Quick Start 优化)
官方参考:
6.1 先确认 Workflow Controller 可处理 argo 命名空间(可选但推荐)
本文统一把 Workflow/EventSource/Sensor 部署在
argo命名空间。若你的 Workflow Controller 不是 cluster-scope,需要确保其 watch 到该命名空间。
# 查看 Workflow Controller
kubectl get deploy -n argo | grep workflow-controller
# 如需指定 watch 命名空间(按你前文的 release 名称示例)
kubectl patch configmap argo-workflows-workflow-controller-configmap -n argo --type merge -p '{"data":{"workflowNamespaces":"argo"}}'
kubectl rollout restart deploy argo-workflows-workflow-controller -n argo
6.2 创建 EventBus(官方常用 native NATS 形态)
kubectl apply -n argo -f - <<'EOF'
apiVersion: argoproj.io/v1alpha1
kind: EventBus
metadata:
name: default
spec:
nats:
native:
replicas: 1
EOF
6.3 创建 Webhook EventSource(与官方命名风格一致)
kubectl apply -n argo -f - <<'EOF'
apiVersion: argoproj.io/v1alpha1
kind: EventSource
metadata:
name: webhook
spec:
service:
ports:
- port: 12000
targetPort: 12000
webhook:
example:
port: "12000"
endpoint: /example
method: POST
EOF
6.4 创建 Sensor 触发 Workflow 所需 SA/RBAC(业务级权限)
kubectl apply -n argo -f - <<'EOF'
apiVersion: v1
kind: ServiceAccount
metadata:
name: operate-workflow-sa
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: operate-workflow-role
rules:
- apiGroups: ["argoproj.io"]
resources: ["workflows"]
verbs: ["create", "get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: operate-workflow-rolebinding
subjects:
- kind: ServiceAccount
name: operate-workflow-sa
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: Role
name: operate-workflow-role
EOF
6.5 创建 Sensor(Webhook 到达后创建 Workflow)
kubectl apply -n argo -f - <<'EOF'
apiVersion: argoproj.io/v1alpha1
kind: Sensor
metadata:
name: webhook-sensor
spec:
template:
serviceAccountName: operate-workflow-sa
dependencies:
- name: webhook-dep
eventSourceName: webhook
eventName: example
triggers:
- template:
name: trigger-workflow
k8s:
operation: create
source:
resource:
apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
generateName: webhook-triggered-
namespace: argo
spec:
serviceAccountName: argo-workflow
entrypoint: whalesay
templates:
- name: whalesay
container:
image: busybox:1.36
command: [sh, -c]
args: ["echo Triggered by Argo Events"]
EOF
6.6 补充 Workflow 运行账号的最小 RBAC(修复 workflowtaskresults 权限)
官方参考:
kubectl apply -n argo -f - <<'EOF'
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: argo-workflow-executor
rules:
- apiGroups: ["argoproj.io"]
resources: ["workflowtaskresults"]
verbs: ["create", "patch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: argo-workflow-executor-binding
subjects:
- kind: ServiceAccount
name: argo-workflow
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: Role
name: argo-workflow-executor
EOF
7. 触发与验证
官方参考:
7.1 暴露 EventSource 服务
kubectl port-forward -n argo svc/webhook-eventsource-svc 12000:12000 --address 0.0.0.0
7.2 发送测试请求
curl -X POST http://127.0.0.1:12000/example -H "Content-Type: application/json" -d '{"message":"hello argo events"}'
7.3 查看执行结果
# 查看 sensor / eventsource
$ kubectl get sensor,eventsource -n argo
NAME AGE
sensor.argoproj.io/webhook-sensor 6m30s
NAME AGE
eventsource.argoproj.io/webhook 6m54s
# 查看 workflow
$ kubectl get wf -n argo
NAME STATUS AGE MESSAGE
webhook-triggered-78hfv Succeeded 2m2s
# 查看 workflow 日志
$ kubectl logs -n argo -l workflows.argoproj.io/workflow -f
Triggered by Argo Events
time="2026-03-05T02:07:49.732Z" level=info msg="sub-process exited" argo=true error="<nil>"
8. 常见问题
8.1 Sensor 报权限错误
重点检查:
operate-workflow-sa是否配置在 SensorserviceAccountNameRole/RoleBinding是否允许创建argoproj.io/workflows- 目标 Workflow 命名空间是否正确(本文为
argo)
8.2 EventBus 未就绪
kubectl describe eventbus default -n argo
kubectl get pods -n argo
8.3 CRD 资源不存在
kubectl get crd | grep argoproj.io
如缺失,重新执行 Helm 安装并保留 CRD 参数。
8.4 workflowtaskresults.argoproj.io is forbidden
现象(常见报错):
wait: Error (exit code 64): workflowtaskresults.argoproj.io is forbidden
原因:
- Workflow 未指定
spec.serviceAccountName,默认使用defaultSA - 该 SA(或你指定的 SA)缺少
workflowtaskresults的create/patch权限
处理:
- 按第 6.5 节确保 Workflow 指定
serviceAccountName: argo-workflow - 按第 6.6 节为该 SA 绑定 executor 最小权限
- 重新触发一次 Webhook 生成新 Workflow(旧 Workflow 不会自动继承新配置)
可选清理旧实例:
kubectl get wf -n argo
kubectl delete wf <旧的workflow名称> -n argo
9. 卸载
# 卸载 Argo Events
helm uninstall argo-events -n argo
# 卸载 Argo Workflows
helm uninstall argo-workflows -n argo
# 删除统一命名空间(如果该命名空间没有其他业务)
kubectl delete namespace argo
# 可选:卸载 ArgoCD
helm uninstall argocd -n argo-cd
kubectl delete namespace argo-cd
10. 小结
这套方案把 Argo Events 的关键链路完整打通了:
- Kind 提供本地高可用测试集群
- Argo Events 负责事件接入与触发
- Argo Workflows 负责被触发后的流程执行
- ArgoCD 可选用于后续 GitOps 化管理 EventSource/Sensor/Workflow 模板(本文 Events/Workflows 统一在
argo命名空间)
如果你要下一步落地到生产环境,建议在此基础上补充:
- EventBus 高可用(NATS Streaming/JetStream)
- 命名空间隔离与最小权限 RBAC
- Webhook 鉴权(Token/HMAC)
- Workflow 模板化与 GitOps 托管(ArgoCD)