Argo Workflows Executor 插件(Executor Plugin)开发实战:零改动扩展工作流引擎
Argo Workflows Executor 插件(Executor Plugin)开发实战:零改动扩展工作流引擎
Executor Plugins 是 Argo Workflows 提供的官方插件扩展机制,它允许开发者以容器化应用 + HTTP RPC 的方式为工作流引擎添加全新能力,而无需修改 Argo Workflows 核心代码、无需等待新版本发布。本指南以 docs/plugins.md 及其配套的 docs/executor_plugins.md、docs/executor_swagger.md 为骨架,结合仓库内 controller 与 agent 的源码实现,系统讲解 Executor 插件的启用配置、Agent Pod 架构、RPC 契约、开发与发布全流程。读完本文,你将能够从零编写一个可运行、可发布的自定义 Executor 插件,并理解其底层运行机制。
什么是 Executor Plugin:为什么需要它
Argo Workflows 本身已经内置了容器、脚本、DAG、HTTP 等丰富的模板类型,但真实的业务场景总是超出框架边界——你可能需要执行一次 AWS SageMaker 训练、同步一个 Argo CD 应用、向 Slack 发送通知,或者运行一个 Chaos Mesh 实验。如果这些能力都要写进核心代码库,Argo Workflows 的发布节奏将成为你的瓶颈。
Executor Plugin 正是为此设计的:它是一个容器化的应用程序,通过响应 RPC HTTP 请求来执行模板。官方文档明确给出了它的三个核心特性:
- 无需修改代码库:新增能力不需要改动 Argo Workflows 本体,可以快速迭代、即时生效;
- 任何语言皆可:插件只是响应 HTTP 请求的进程,你不需要学习 Golang 也能扩展 Argo Workflows;
- 共享 Agent Pod:插件运行在控制器创建并管理的专用
agentPod 中,每个正在运行的工作流只使用一个 Agent Pod。当多个步骤复用同一个插件时,这种架构能显著提升性能;同一个 Agent Pod 还会运行工作流中任何 HTTP 模板,带来额外的性能优势。
插件的定义方式是一个 ExecutorPlugin 自定义资源,普通用户和管理员都可以编写并安装它。从源码看,ExecutorPlugin 的载体其实是带特定标签的 ConfigMap——控制器通过 ConfigMap informer 动态发现插件,因此你可以随时增删插件而无需重启控制器(详见下文"控制器如何发现插件")。
与其他插件类型的分工
除了 Executor Plugin,Argo Workflows 还支持另一类扩展:
- Artifact Plugin(工件插件):扩展工件存储能力,接入自定义存储驱动。Artifact 插件以 gRPC 服务器 + Unix Socket 的形式实现,通过
artifact.proto(pkg/apiclient/artifact/artifact.proto)定义接口,需要实现Load、Save、Delete、ListObjects、IsDirectory、OpenStream等方法。
两者的定位截然不同:Executor Plugin 扩展"模板能做什么"(执行逻辑),Artifact Plugin 扩展"工件存到哪"(存储后端)。本文聚焦前者。
启用 Executor 插件:全局与工作流级两种开关
Executor Plugins 在默认情况下是关闭的。启用方式有两种,相互独立,可以单独开启、也可以同时开启:
| 环境变量 | 作用 |
|---|---|
ARGO_EXECUTOR_PLUGINS=true |
启用定义在控制器 ConfigMap 中的全局 Executor 插件 |
ARGO_WORKFLOW_LEVEL_EXECUTOR_PLUGINS=true |
允许在 Workflow spec 内直接声明插件配置,且工作流级配置优先于全局配置 |
在 Workflow Controller Deployment 中同时启用两种模式的完整示例:
apiVersion: apps/v1
kind: Deployment
metadata:
name: workflow-controller
spec:
template:
spec:
containers:
- name: workflow-controller
env:
- name: ARGO_EXECUTOR_PLUGINS
value: "true"
- name: ARGO_WORKFLOW_LEVEL_EXECUTOR_PLUGINS
value: "true"
如果使用 Helm chart 部署,则在 values.yaml 中追加:
controller:
extraEnv:
- name: ARGO_EXECUTOR_PLUGINS
value: "true"
- name: ARGO_WORKFLOW_LEVEL_EXECUTOR_PLUGINS
value: "true"
关于这两个开关的源码佐证,见 workflow/controller/controller.go 中 executorPlugins 与 enableWorkflowLevelExecutorPlugins 两个字段,以及 workflow/controller/agent.go 中 getExecutorPlugins 对后者的强制校验——若工作流中声明了插件而控制器未开启工作流级开关,会直接报错并提示设置 ARGO_WORKFLOW_LEVEL_EXECUTOR_PLUGINS=true。
工作流级插件示例
参考官方示例 examples/workflow-level-executor-plugin.yaml,可以在 Workflow spec 的 executorPlugins 字段中直接内联一个完整的 Python 插件(HTTP 服务端监听 4356 端口)。该示例的注释明确说明:一旦设置了 spec.executorPlugins,控制器 ConfigMap 中配置的全局插件对该工作流将被忽略。
apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
generateName: workflow-level-executor-plugin-
spec:
entrypoint: main
executorPlugins:
- metadata:
name: workflow-level-hello-executor-plugin
spec:
sidecar:
container:
name: workflow-level-hello-executor-plugin
image: python:alpine3.23
command: [python, -c]
args:
- | # 内联一段完整 Python HTTP 服务代码
...
ports:
- containerPort: 4356
resources:
limits: {cpu: 200m, memory: 64Mi}
requests: {cpu: 100m, memory: 32Mi}
securityContext:
allowPrivilegeEscalation: false
capabilities: {drop: [ALL]}
readOnlyRootFilesystem: true
runAsNonRoot: true
templates:
- name: main
plugin:
workflowLevelHello: {}
架构剖析:Agent Pod 与 RPC 调用链
要写出正确的插件,必须理解它的运行环境。当工作流中某个模板声明了 plugin: 字段时,控制器会做以下事情(对应 workflow/controller/agent.go 的 createAgentPod):
- 为工作流创建一个名为
<workflow-node-id>-agent的 Agent Pod(getAgentPodName,见 workflow/controller/agent.go); - Agent Pod 由
init容器(argoexec agent init)和main容器(argoexec agent main)组成,插件 sidecar 容器会与 main 容器一同调度进该 Pod(workflow/controller/agent.go); - 控制器把插件地址列表(
http://localhost:<port>)与插件名称列表通过环境变量注入 Agent(workflow/controller/agent.go); - 插件 sidecar 会获得一个只读挂载到
/var/run/argo的 token 卷(SubPath为该插件容器名,保证每个插件只拿到自己的 token),供 RPC 认证使用(workflow/controller/agent.go)。
Agent 端发起 RPC 调用的客户端实现在 workflow/executor/plugins/rpc/plugin.go:New(address, token) 创建一个带 30 秒超时和指数退避(wait.Backoff{Duration: 1s, Jitter: 0.2, Factor: 2, Steps: 5})的 HTTP 客户端,ExecuteTemplate 方法对应 RPC 方法名 template.execute。这就是插件需要实现 HTTP 端点 /api/v1/template.execute 的原因。
控制器如何发现插件
控制器启动时若启用了 Executor 插件,会注册一个 ConfigMap informer,只关注带标签 workflows.argoproj.io/configmap-type=ExecutorPlugin 的 ConfigMap(workflow/controller/controller.go)。ConfigMap 的新增、更新、删除会实时反映到控制器内存中的插件表(namespace -> name -> plugin),并打印 Executor plugin added/updated/removed 日志。因此:
- 插件本质是带特殊标签的 ConfigMap,可以用
kubectl直接查看; - 插件的发现范围是:工作流所在的 namespace + Argo 安装 namespace(通常为
argo); - 如果两个 namespace 中存在同名插件,只加载工作流 namespace 中的那个。
实战:从零编写一个 Python Executor 插件
接下来完整实现官方文档中"Hello World"级别的 Python 插件——每次工作流被操作时打印 "hello"。开发一个 Executor 插件需要四样东西:
- 在 Workflow Controller 上启用 Executor 插件(见上文配置);
- 用于运行和管理 Agent Pod 的额外 RBAC 权限(见 docs/http-template.md 中关于 Agent Pod RBAC 的说明);
- 一个 HTTP 服务器,作为主容器的 sidecar 运行,按照 docs/executor_swagger.md 描述的 API 契约响应来自 executor 的 RPC 请求;
- 一个
plugin.yaml配置文件,被转换为 ConfigMap 供控制器发现。
第一步:用 curl 验证 RPC 契约
模板型 Executor 插件在 /api/v1/template.execute 上服务 HTTP POST 请求。请求体包含工作流元数据和待执行的模板,其中 template.plugin 下的键就是插件名:
curl http://localhost:4355/api/v1/template.execute -d \
'{
"workflow": {
"metadata": {
"name": "my-wf"
}
},
"template": {
"name": "my-tmpl",
"inputs": {},
"outputs": {},
"plugin": {
"hello": {}
}
}
}'
# ...
HTTP/1.1 200 OK
{
"node": {
"phase": "Succeeded",
"message": "Hello template!"
}
}
端口选择建议:端口号可以任意,但不能与其他 Executor 插件冲突。不要使用 80、443、8080、8081、8443 等常见端口。如果打算发布插件,请选择一个小于 10000 的随机端口并通过 PR 注册;否则使用大于 10000 的端口。
第二步:编写 HTTP 服务端(server.py)
import json
from http.server import BaseHTTPRequestHandler, HTTPServer
with open("/var/run/argo/token") as f:
token = f.read().strip()
class Plugin(BaseHTTPRequestHandler):
def args(self):
return json.loads(self.rfile.read(int(self.headers.get('Content-Length'))))
def reply(self, reply):
self.send_response(200)
self.end_headers()
self.wfile.write(json.dumps(reply).encode("UTF-8"))
def forbidden(self):
self.send_response(403)
self.end_headers()
def unsupported(self):
self.send_response(404)
self.end_headers()
def do_POST(self):
if self.headers.get("Authorization") != "Bearer " + token:
self.forbidden()
elif self.path == '/api/v1/template.execute':
args = self.args()
if 'hello' in args['template'].get('plugin', {}):
self.reply(
{'node': {'phase': 'Succeeded', 'message': 'Hello template!',
'outputs': {'parameters': [{'name': 'foo', 'value': 'bar'}]}}})
else:
self.reply({})
else:
self.unsupported()
if __name__ == '__main__':
httpd = HTTPServer(('', 4355), Plugin)
httpd.serve_forever()
对这段代码,官方文档给出如下关键提示,请务必逐条落实:
- 只实现你需要的 RPC 方法:返回 404 的方法之后不会再被调用;
- 路径即 RPC 方法名:
/api/v1/template.execute对应template.execute; - 必须校验认证:
Authorization请求头应等于/var/run/argo/token文件中的内容,否则返回 403; - 请求体携带模板的输入参数(
workflow与template两个字段); - 响应体可以携带节点结果,包括
phase(如Succeeded或Failed)和message; - 响应为
{}表示该插件无法执行这个 Plugin 模板——例如它是 Slack 插件,但模板是一个 Tekton 任务; - 返回 404 表示该方法不被支持,之后不再调用;
- 如果你把脚本文件命名为
server.*,它会被自动复制到 sidecar 容器的args字段——这对于 Python、Node.JS 等脚本语言构建自包含插件非常方便(参考上面的args: python -c <脚本>用法)。
第三步:编写插件清单 plugin.yaml
apiVersion: argoproj.io/v1alpha1
kind: ExecutorPlugin
metadata:
name: hello
spec:
sidecar:
container:
command:
- python
- -u # disables output buffering
- -c
image: python:alpine3.23
name: hello-executor-plugin
ports:
- containerPort: 4355
securityContext:
runAsNonRoot: true
runAsUser: 65534 # nobody
resources:
requests:
memory: "64Mi"
cpu: "250m"
limits:
memory: "128Mi"
cpu: "500m"
注意清单的 spec.sidecar.container 是标准的 Kubernetes Container 结构(对应源码 pkg/plugins/spec/plugin_types.go 中的 Sidecar 类型),因此镜像、命令、端口、资源、安全上下文、环境变量、探针等字段全部可用。
第四步:构建、安装并验证
argo executor-plugin build .
kubectl -n argo apply -f hello-executor-plugin-configmap.yaml
构建命令会基于 plugin.yaml 生成一个带 workflows.argoproj.io/configmap-type=ExecutorPlugin 标签的 ConfigMap(hello-executor-plugin-configmap.yaml)。argo executor-plugin build 子命令位于 cmd/argo/commands 目录下。安装后检查控制器日志,应看到:
level=info msg="Executor plugin added" name=hello-controller-plugin
然后运行一个使用该插件的工作流:
apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
generateName: hello-
spec:
entrypoint: main
templates:
- name: main
plugin:
hello: { }
工作流将成功完成——控制器发现模板里有 plugin.hello 字段后,会通过 Agent Pod 调用插件 sidecar 的 /api/v1/template.execute,插件返回 Succeeded,模板随即成功。
RPC API 契约详解
插件必须实现的 API 契约定义在 docs/executor_swagger.md(版本 0.0.1),其 Go 类型定义在 pkg/plugins/executor/template_executor_plugin.go:
端点:POST /api/v1/template.execute(消费与产出均为 application/json)。
请求体(ExecuteTemplateArgs):
| 字段 | 类型 | 说明 |
|---|---|---|
workflow |
Workflow |
正在运行的工作流对象 |
template |
Template |
待执行的模板,template.plugin 下的键标识要调用的插件 |
响应体(ExecuteTemplateReply):
| 字段 | 类型 | 说明 |
|---|---|---|
node |
NodeResult(可选) |
节点结果,包含 phase(Succeeded/Failed/Running/Pending 等)、message、outputs(可回传输出参数,如示例中的 outputs.parameters) |
requeue |
Duration(可选) |
重新入队时间,例如 "2m" |
Secrets:不要硬编码第三方凭据
如果插件需要与第三方系统交互,不要把凭据写进 plugin.yaml,而是使用 Kubernetes Secret 并通过 secretKeyRef 注入环境变量:
spec:
sidecar:
container:
env:
- name: URL
valueFrom:
secretKeyRef:
name: slack-executor-plugin
key: URL
关于 Secret 的最佳实践与安全考量,参考 Kubernetes 官方 Secret 文档。需要指出的是,插件 sidecar 还可以通过 automountServiceAccountToken 选项挂载同名 ServiceAccount 的 token(见 pkg/plugins/spec/plugin_types.go),以便插件调用 Kubernetes API。
强制约束:资源与安全上下文
控制器对插件清单有强制校验(源码见 pkg/plugins/spec/plugin_types.go 的 Sidecar.Validate):
- 至少声明一个端口;
- 必须声明
resources.requests和resources.limits; - 必须声明
securityContext。
这些约束的目的,是防止任何人创建使用不合理内存、或以 root 身份运行的插件(除非有意为之):
spec:
sidecar:
container:
resources:
requests:
cpu: 100m
memory: 32Mi
limits:
cpu: 200m
memory: 64Mi
securityContext:
runAsNonRoot: true
runAsUser: 1000
失败语义与重试
Executor 插件的失败分为两类(详见 docs/executor_plugins.md):
| 错误类型 | 是否重试 | 说明 |
|---|---|---|
| 连接/Socket 错误 | 暂时性,重试 | 网络抖动等 |
| 超时 | 暂时性,重试 | |
| 404 | 不再调用 | 方法不被该插件支持(同一工作流内) |
| 503 | 暂时性,重试 | 服务不可用 |
| 其他 4xx/5xx | 致命 | 步骤直接失败 |
致命错误会导致步骤失败;暂时性错误则由系统自动重试。
Re-Queue:处理长时间运行的任务
有时插件无法立即完成工作——例如它启动了一个长时间运行的任务。此时返回 Running(或 Pending)状态并附带一个重新入队时间:
{
"node": {
"phase": "Running",
"message": "Long-running task started"
},
"requeue": "2m"
}
上例中,任务将被重新入队,2 分钟后 template.execute 会再次被调用。requeue 字段对应源码中 ExecuteTemplateReply.Requeue *metav1.Duration(pkg/plugins/executor/template_executor_plugin.go)。
调试、列出与发布
查看插件日志:插件日志位于 Agent Pod 的 sidecar 容器中,用 kubectl logs 直接查看:
kubectl -n argo logs ${agentPodName} -c hello-executor-plugin
列出已安装的插件:因为插件本质是 ConfigMap,直接按标签过滤即可:
kubectl get cm -l workflows.argoproj.io/configmap-type=ExecutorPlugin
发布插件:如果你愿意分享自己的插件(官方鼓励这样做),向 docs/plugin-directory.md 提交 Pull Request 将其加入目录即可。该目录目前收录了 Hello、Slack、Argo CD、Volcano Job、Python、WASM、Chaos Mesh、AWS、Pytorch Job、Ray Job 等社区插件,可以作为参考模板。注意目录页有明确免责声明:官方只对插件真实性做最小程度的验证,安装使用需自担风险。
总结
Executor Plugin 是 Argo Workflows 扩展能力的官方推荐路径:它把"模板执行"这个核心动作抽象为一次 HTTP RPC(POST /api/v1/template.execute),让任何语言的开发者都能以容器 sidecar 的形式注入自定义逻辑,并借助共享 Agent Pod 获得性能优势。开发流程可归纳为四步——写一个 HTTP 服务、写一份 plugin.yaml、argo executor-plugin build 生成 ConfigMap、kubectl apply 安装;再配合全局/工作流级两种开关、强制资源与安全约束、明确的失败/重试/Re-queue 语义,你可以在不改动 Argo Workflows 代码库的前提下,快速搭建属于自己的工作流能力生态。
进一步阅读:插件 API 契约见 docs/executor_swagger.md;配置细节见 docs/executor_plugins.md;工作流级插件完整示例见 examples/workflow-level-executor-plugin.yaml;若需扩展工件存储,见 docs/artifact-plugin.md。