1545 字

8 分钟

Argo Events 完全实战指南

2026-03-05

Argo

/

ArgoCD Events

Argo Events 完全实战指南#

1. Argo Events 简介#

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

核心组件：

EventSource：负责接收事件
EventBus：负责事件传输（通常基于 NATS）
Sensor：负责消费事件并触发动作

2. 环境准备#

2.1 搭建 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. ArgoCD 部署#

参考argocd简介及多种模式部署来在kind集群安装ArgoCD。

3.1 部署 ArgoCD#

1
# 更新helm repo
2
helm repo add argo https://argoproj.github.io/argo-helm
3
helm repo update
4

5
# 部署argocd
6
helm upgrade --install argocd argo/argo-cd \
7
  --version 7.3.5 \
8
  --namespace argo \
9
  --create-namespace

如果网络存在问题，也可以从本地chart进行安装：

1
helm pull argo/argo-cd --version 7.3.5
2
helm upgrade --install argocd ./argo-cd-7.3.5.tgz \
3
  --namespace argo \
4
  --create-namespace

3.2 暴露 ArgoCD 服务#

1
# 使用端口转发访问 UI
2
kubectl port-forward svc/argocd-server -n argo 8080:443 --address 0.0.0.0

3.3 获取初始密码#

1
# 获取初始管理员密码
2
kubectl -n argo get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d

4. Argo Workflows 部署#

1
# 添加 Argo Helm 仓库
2
helm repo add argo https://argoproj.github.io/argo-helm
3
helm repo update
4

5
# 安装 Argo Workflows（测试环境配置）
6
helm upgrade --install argo-workflows argo/argo-workflows \
7
  --version 0.47.4 \
8
  --namespace argo \
9
  --create-namespace \
10
  --set server.secure=false \
11
  --set server.extraArgs[0]="--auth-mode=server" \
12
  --set workflow.serviceAccount.create=true \
13
  --set workflow.serviceAccount.name=argo-workflow \
14
  --set workflow.rbac.create=true \
15
  --set 'workflow.rbac.rules[0].apiGroups[0]=' \
16
  --set 'workflow.rbac.rules[0].apiGroups[1]=apps' \
17
  --set 'workflow.rbac.rules[0].resources[0]=*' \
18
  --set 'workflow.rbac.rules[0].verbs[0]=*'

验证：

1
kubectl get pods -n argo -w

5. 使用 Helm 部署 Argo Events#

官方参考：

5.1 安装 Argo Events#

1
# 添加仓库
2
helm repo add argo https://argoproj.github.io/argo-helm
3
helm repo update
4

5
# 统一使用 Helm 安装，并显式开启 CRDs/RBAC 相关项
6
helm upgrade --install argo-events argo/argo-events \
7
  --namespace argo \
8
  --create-namespace \
9
  --set installCRDs=true \
10
  --set crds.install=true \
11
  --set rbac.create=true

说明：不同 chart 版本字段可能略有差异，这里同时设置 installCRDs 与 crds.install，以覆盖常见版本写法；RBAC 由 Helm 安装阶段直接创建。

5.2 验证安装#

1
kubectl get pods -n argo
2
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 到该命名空间。

1
# 查看 Workflow Controller
2
kubectl get deploy -n argo | grep workflow-controller
3

4
# 如需指定 watch 命名空间（按你前文的 release 名称示例）
5
kubectl patch configmap argo-workflows-workflow-controller-configmap -n argo --type merge -p '{"data":{"workflowNamespaces":"argo"}}'
6
kubectl rollout restart deploy argo-workflows-workflow-controller -n argo

6.2 创建 EventBus（官方常用 native NATS 形态）#

1
kubectl apply -n argo -f - <<'EOF'
2
apiVersion: argoproj.io/v1alpha1
3
kind: EventBus
4
metadata:
5
  name: default
6
spec:
7
  nats:
8
    native:
9
      replicas: 1
10
EOF

6.3 创建 Webhook EventSource（与官方命名风格一致）#

1
kubectl apply -n argo -f - <<'EOF'
2
apiVersion: argoproj.io/v1alpha1
3
kind: EventSource
4
metadata:
5
  name: webhook
6
spec:
7
  service:
8
    ports:
9
      - port: 12000
10
        targetPort: 12000
11
  webhook:
12
    example:
13
      port: "12000"
14
      endpoint: /example
15
      method: POST
16
EOF

6.4 创建 Sensor 触发 Workflow 所需 SA/RBAC（业务级权限）#

1
kubectl apply -n argo -f - <<'EOF'
2
apiVersion: v1
3
kind: ServiceAccount
4
metadata:
5
  name: operate-workflow-sa
6
---
7
apiVersion: rbac.authorization.k8s.io/v1
8
kind: Role
9
metadata:
10
  name: operate-workflow-role
11
rules:
12
  - apiGroups: ["argoproj.io"]
13
    resources: ["workflows"]
14
    verbs: ["create", "get", "list"]
15
---
16
apiVersion: rbac.authorization.k8s.io/v1
17
kind: RoleBinding
18
metadata:
19
  name: operate-workflow-rolebinding
20
subjects:
21
  - kind: ServiceAccount
22
    name: operate-workflow-sa
23
roleRef:
24
  apiGroup: rbac.authorization.k8s.io
25
  kind: Role
26
  name: operate-workflow-role
27
EOF

6.5 创建 Sensor（Webhook 到达后创建 Workflow）#

1
kubectl apply -n argo -f - <<'EOF'
2
apiVersion: argoproj.io/v1alpha1
3
kind: Sensor
4
metadata:
5
  name: webhook-sensor
6
spec:
7
  template:
8
    serviceAccountName: operate-workflow-sa
9
  dependencies:
10
    - name: webhook-dep
11
      eventSourceName: webhook
12
      eventName: example
13
  triggers:
14
    - template:
15
        name: trigger-workflow
16
        k8s:
17
          operation: create
18
          source:
19
            resource:
20
              apiVersion: argoproj.io/v1alpha1
21
              kind: Workflow
22
              metadata:
23
                generateName: webhook-triggered-
24
                namespace: argo
25
              spec:
26
                serviceAccountName: argo-workflow
27
                entrypoint: whalesay
28
                templates:
29
                  - name: whalesay
30
                    container:
31
                      image: busybox:1.36
32
                      command: [sh, -c]
33
                      args: ["echo Triggered by Argo Events"]
34
EOF

6.6 补充 Workflow 运行账号的最小 RBAC（修复 `workflowtaskresults` 权限）#

官方参考：

1
kubectl apply -n argo -f - <<'EOF'
2
apiVersion: rbac.authorization.k8s.io/v1
3
kind: Role
4
metadata:
5
  name: argo-workflow-executor
6
rules:
7
  - apiGroups: ["argoproj.io"]
8
    resources: ["workflowtaskresults"]
9
    verbs: ["create", "patch"]
10
---
11
apiVersion: rbac.authorization.k8s.io/v1
12
kind: RoleBinding
13
metadata:
14
  name: argo-workflow-executor-binding
15
subjects:
16
  - kind: ServiceAccount
17
    name: argo-workflow
18
roleRef:
19
  apiGroup: rbac.authorization.k8s.io
20
  kind: Role
21
  name: argo-workflow-executor
22
EOF

7. 触发与验证#

官方参考：

Webhook EventSource Setup（POST /example）

7.1 暴露 EventSource 服务#

1
kubectl port-forward -n argo svc/webhook-eventsource-svc 12000:12000 --address 0.0.0.0

7.2 发送测试请求#

1
curl -X POST http://127.0.0.1:12000/example -H "Content-Type: application/json" -d '{"message":"hello argo events"}'

7.3 查看执行结果#

1
# 查看 sensor / eventsource
2
$ kubectl get sensor,eventsource -n argo
3
NAME                                AGE
4
sensor.argoproj.io/webhook-sensor   6m30s
5

6
NAME                              AGE
7
eventsource.argoproj.io/webhook   6m54s
8

9
# 查看 workflow
10
$ kubectl get wf -n argo
11
NAME                      STATUS      AGE    MESSAGE
12
webhook-triggered-78hfv   Succeeded   2m2s
13

14
# 查看 workflow 日志
15
$ kubectl logs -n argo -l workflows.argoproj.io/workflow -f
16
Triggered by Argo Events
17
time="2026-03-05T02:07:49.732Z" level=info msg="sub-process exited" argo=true error="<nil>"

8. 常见问题#

8.1 Sensor 报权限错误#

重点检查：

operate-workflow-sa 是否配置在 Sensor serviceAccountName
Role/RoleBinding 是否允许创建 argoproj.io/workflows
目标 Workflow 命名空间是否正确（本文为 argo）

8.2 EventBus 未就绪#

1
kubectl describe eventbus default -n argo
2
kubectl get pods -n argo

8.3 CRD 资源不存在#

1
kubectl get crd | grep argoproj.io

如缺失，重新执行 Helm 安装并保留 CRD 参数。

8.4 `workflowtaskresults.argoproj.io is forbidden`#

现象（常见报错）：

1
wait: Error (exit code 64): workflowtaskresults.argoproj.io is forbidden

原因：

Workflow 未指定 spec.serviceAccountName，默认使用 default SA
该 SA（或你指定的 SA）缺少 workflowtaskresults 的 create/patch 权限

处理：

按第 6.5 节确保 Workflow 指定 serviceAccountName: argo-workflow
按第 6.6 节为该 SA 绑定 executor 最小权限
重新触发一次 Webhook 生成新 Workflow（旧 Workflow 不会自动继承新配置）

可选清理旧实例：

1
kubectl get wf -n argo
2
kubectl delete wf <旧的workflow名称> -n argo

9. 卸载#

1
# 卸载 Argo Events
2
helm uninstall argo-events -n argo
3

4
# 卸载 Argo Workflows
5
helm uninstall argo-workflows -n argo
6

7
# 删除统一命名空间（如果该命名空间没有其他业务）
8
kubectl delete namespace argo
9

10
# 可选：卸载 ArgoCD
11
helm uninstall argocd -n argo-cd
12
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）

Argo Events 完全实战指南

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

作者

花日

发布于

2026-03-05

许可协议

CC BY-NC-SA 4.0

部分信息可能已经过时

基于Kind搭建测试集群

Argo CD Operator 完全实战指南

花日の博客

Argo Events 完全实战指南#

1. Argo Events 简介#

2. 环境准备#

2.1 搭建 Kind 集群#

3. ArgoCD 部署#

3.1 部署 ArgoCD#

3.2 暴露 ArgoCD 服务#

3.3 获取初始密码#

4. Argo Workflows 部署#

5. 使用 Helm 部署 Argo Events#

5.1 安装 Argo Events#

5.2 验证安装#

6. 部署 EventBus / EventSource / Sensor（按官方 Quick Start 优化）#

6.1 先确认 Workflow Controller 可处理 argo 命名空间（可选但推荐）#

6.2 创建 EventBus（官方常用 native NATS 形态）#

6.3 创建 Webhook EventSource（与官方命名风格一致）#

6.4 创建 Sensor 触发 Workflow 所需 SA/RBAC（业务级权限）#

6.5 创建 Sensor（Webhook 到达后创建 Workflow）#

6.6 补充 Workflow 运行账号的最小 RBAC（修复 workflowtaskresults 权限）#

7. 触发与验证#

7.1 暴露 EventSource 服务#

7.2 发送测试请求#

7.3 查看执行结果#

8. 常见问题#

8.1 Sensor 报权限错误#

8.2 EventBus 未就绪#

8.3 CRD 资源不存在#

8.4 workflowtaskresults.argoproj.io is forbidden#

9. 卸载#

10. 小结#

6.1 先确认 Workflow Controller 可处理 `argo` 命名空间（可选但推荐）#

6.6 补充 Workflow 运行账号的最小 RBAC（修复 `workflowtaskresults` 权限）#

8.4 `workflowtaskresults.argoproj.io is forbidden`#