Argo-Events-完全实战指南

1. Argo Events 简介

Argo Events 是 Argo 生态中的事件驱动框架,用于监听外部或内部事件(Webhook、Git、消息队列、定时器等),并通过 Sensor 触发 Kubernetes 资源创建、Argo Workflows 执行等动作。

核心组件:


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 报权限错误

重点检查:

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

原因:

处理:

可选清理旧实例:

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 的关键链路完整打通了:

如果你要下一步落地到生产环境,建议在此基础上补充: