Argo Workflows Executor Plugin 命令与插件开发完全指南:`argo executor-plugin` 从 CLI 参考到实战构建
Argo Workflows Executor Plugin 命令与插件开发完全指南:argo executor-plugin 从 CLI 参考到实战构建
Executor Plugin 是 Argo Workflows 提供的一种可插拔机制,允许用户以 HTTP 服务的形式自定义 Plugin 类型模板的执行逻辑,从而将 Slack 通知、Argo CD 同步、Ray 任务等第三方能力无缝接入工作流。本文以 argo executor-plugin 命令为核心,系统讲解该 CLI 的完整参数语义、argo executor-plugin build 的构建流程,并结合仓库源码深入剖析插件清单结构、RPC 契约、发现机制、重试与重新排队语义,帮助你从零构建、安装、调试并发布一个属于自己的 Executor Plugin。
一、命令概览:argo executor-plugin
argo executor-plugin 是 Argo CLI(argo)下的一个管理子命令组,用于管理 Executor Plugin。其命令定义为:
argo executor-plugin [flags]
在源码层面,该命令由 cmd/argo/commands/executorplugin/root.go 定义:NewRootCommand() 设置了 Use: "executor-plugin"、Short: "manage executor plugins",当不带子命令直接运行时,会输出命令帮助信息(RunE 返回 cmd.Help())。当前仓库中该命令组只注册了一个子命令:
argo executor-plugin build DIR—— 构建一个 Executor Plugin,将其打包为可安装的 ConfigMap 清单(见下文)。
命令自身的选项只有标准帮助参数:
Options:
-h, --help help for executor-plugin
继承自父命令的全局参数
argo executor-plugin 与其子命令 build 都会继承 Argo CLI 的全套全局参数,用于指定 API Server 地址、认证方式、kubeconfig、TLS 与日志级别等。这些参数与 argo 根命令完全一致,完整清单如下(表中同时给出默认值与取值说明):
| 参数 | 类型 | 说明 |
|---|---|---|
--argo-base-href string |
string | 由于 Base HREF 而需要在 HTTP 客户端中使用的路径。默认读取 ARGO_BASE_HREF 环境变量 |
--argo-http1 |
bool | 若为 true,则使用 HTTP 客户端。默认读取 ARGO_HTTP1 环境变量 |
-s, --argo-server host:port |
string | API Server 地址,形如 localhost:2746。默认读取 ARGO_SERVER 环境变量 |
--as string |
string | 模拟操作所使用的用户名(User Impersonation) |
--as-group stringArray |
string 数组 | 模拟操作所使用的用户组,可重复指定多个组 |
--as-uid string |
string | 模拟操作所使用的 UID |
--certificate-authority string |
string | 证书颁发机构(CA)证书文件路径 |
--client-certificate string |
string | TLS 客户端证书文件路径 |
--client-key string |
string | TLS 客户端密钥文件路径 |
--cluster string |
string | 要使用的 kubeconfig 集群名称 |
--context string |
string | 要使用的 kubeconfig 上下文名称 |
--disable-compression |
bool | 若为 true,则对所有发往服务器的请求关闭响应压缩 |
--gloglevel int |
int | 设置 glog 日志级别 |
-H, --header strings |
string 列表 | 为 Argo CLI 发起的全部请求附加额外 Header(可多次指定,也支持逗号分隔),仅在 ARGO_HTTP1 或 --argo-http1 为 true 时生效 |
--insecure-skip-tls-verify |
bool | 若为 true,则不校验服务器证书有效性,会使 HTTPS 连接不安全 |
-k, --insecure-skip-verify |
bool | 若为 true,则不校验 Argo Server 证书有效性。默认读取 ARGO_INSECURE_SKIP_VERIFY 环境变量 |
--instanceid string |
string | 以特定控制器的 instance id 标签提交。默认读取 ARGO_INSTANCEID 环境变量 |
--kubeconfig string |
string | kubeconfig 文件路径,仅在集群外运行时需要 |
--log-format string |
string | 日志输出格式,取值为 text 或 json(默认 text) |
--loglevel string |
string | 日志级别,取值为 debug、info、warn、error(默认 info) |
-n, --namespace string |
string | 本次 CLI 请求的命名空间作用域 |
--password string |
string | 访问 API Server 的基本认证密码 |
--proxy-url string |
string | 若提供,则通过该代理 URL 建立连接 |
--request-timeout string |
string | 单个服务器请求的超时时间,非零值需带时间单位(如 1s、2m、3h),零值表示不超时(默认 0) |
-e, --secure |
bool | 是否使用 TLS 连接 Argo Server。默认读取 ARGO_SECURE 环境变量(默认 true) |
--server string |
string | Kubernetes API Server 的地址与端口 |
--tls-server-name string |
string | 用于校验服务器证书的名称;未提供时使用连接服务器的主机名 |
--token string |
string | 访问 API Server 的 Bearer Token |
--user string |
string | 要使用的 kubeconfig 用户名 |
--username string |
string | 访问 API Server 的基本认证用户名 |
-v, --verbose |
bool | 开启详细日志,等价于 --loglevel debug |
说明:
argo executor-plugin本身并不直接与 API Server 交互(构建是纯本地操作),但这些继承参数是 Argo CLI 命令族的统一约定,保证在任何子命令下行为一致。
二、argo executor-plugin build:构建插件清单
构建命令的完整语法为:
argo executor-plugin build DIR [flags]
其中 DIR 是插件源码所在目录(必填参数,且只接受一个目录参数)。其作用是将目录内的插件清单 plugin.yaml 与可选的 server.* 脚本文件,打包成一个可直接通过 kubectl apply 安装的 ConfigMap 清单文件,并顺带生成一份插件 README。
构建命令的源码级流程
从 cmd/argo/commands/executorplugin/build.go 可以看到构建过程分为四步:
- 读取并校验清单:
loadPluginManifest(pluginDir)读取目录下的plugin.yaml,使用yaml.UnmarshalStrict严格反序列化为spec.Plugin结构,并调用p.Validate()校验(校验规则见下文"清单结构与强制校验")。 - 收集
server.*脚本:通过filepath.Glob(filepath.Join(pluginDir, "server.*"))查找目录下的脚本文件。如果找到超过一个server.*文件,直接报错"plugin %s has more than one server.* file";如果恰好一个,则将该文件内容整体读入,写入spec.sidecar.container.args(这正是"把server.py作为容器启动参数"的实现来源,详见 cmd/argo/commands/executorplugin/io.go)。 - 转换为 ConfigMap:
plugin.ToConfigMap(plug)将插件定义转换为带标签的 ConfigMap(见下文)。 - 落盘输出:
saveConfigMap将 ConfigMap 序列化写入DIR/<插件名>-executor-plugin-configmap.yaml(文件头部自动加上# This is an auto-generated file. DO NOT EDIT注释);saveReadme在同一目录生成README.md,内容包含插件所需的 Argo 版本注解、镜像地址与安装/卸载命令。
构建完成后控制台会打印生成的两个文件路径,例如:
hello-executor-plugin-configmap.yaml created
README.md created
生成的 ConfigMap 内部结构
workflow/util/plugin/configmap.go 中的 ToConfigMap 展示了转换规则:ConfigMap 名为 <插件名>-executor-plugin,带标签 workflows.argoproj.io/configmap-type: ExecutorPlugin(对应 workflow/common/common.go 中的 LabelKeyConfigMapType 与 LabelValueTypeConfigMapExecutorPlugin 常量),数据区包含两个键:
sidecar.automountServiceAccountToken:布尔字符串,表示是否自动挂载同名 ServiceAccount 的 Token;sidecar.container:插件 sidecar 容器的完整 YAML 定义(即plugin.yaml中spec.sidecar.container的内容)。
而 FromConfigMap 则执行逆过程——这也是控制器从 ConfigMap 恢复插件定义所走的路径,二者相互印证了"Executor Plugin 本质上是 ConfigMap"这一事实。
三、理解 Executor Plugin:概念与启用方式
Executor Plugin 默认是关闭的,需要在 Workflow Controller 中显式开启。它有两种作用域,二者相互独立、可以同时开启:
| 环境变量 | 作用 |
|---|---|
ARGO_EXECUTOR_PLUGINS=true |
启用定义在控制器 ConfigMap 中的全局 Executor Plugin |
ARGO_WORKFLOW_LEVEL_EXECUTOR_PLUGINS=true |
允许在 Workflow Spec 中直接声明 Executor Plugin 设置;工作流级别的设置优先级高于全局设置 |
在 workflow/controller/controller.go 中,这两个开关分别对应控制器上的 executorPlugins 映射(namespace -> name -> plugin)与 enableWorkflowLevelExecutorPlugins 布尔标志,它们由 NewWorkflowController 的 executorPlugins bool, workflowLevelExecutorPlugins bool 参数注入。
在 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"
仓库的快速安装清单(如 manifests/quick-start-minimal.yaml、manifests/quick-start-postgres.yaml 等)中也已默认写入这两个环境变量,可作为参考。
工作流级别的 Executor Plugin
工作流级别插件通过 Workflow Spec 顶层的 spec.executorPlugins 字段声明,每个条目是一个与 plugin.yaml 同构的内联定义(metadata + spec.sidecar.container)。完整的可运行示例见 examples/workflow-level-executor-plugin.yaml,其中以 python:alpine3.23 镜像内联了一段 Python HTTP 服务,监听 4356 端口并在收到 workflowLevelHello 插件调用时返回 Succeeded。
需要特别注意的是:当 spec.executorPlugins 存在时,该工作流会忽略控制器 ConfigMap 中的全局插件配置。这一行为在 workflow/controller/agent.go 的 getExecutorPlugins 中有明确体现:如果从 Workflow Spec 解析出插件,就走工作流级别分支;否则才遍历工作流命名空间与控制命名空间中的全局插件。同时,若工作流声明了插件而控制器未开启 ARGO_WORKFLOW_LEVEL_EXECUTOR_PLUGINS,控制器会直接报错提示开启对应环境变量。
四、插件清单 plugin.yaml 的结构与强制校验
一个 Executor Plugin 目录下必须包含 plugin.yaml,其结构如下:
apiVersion: argoproj.io/v1alpha1
kind: ExecutorPlugin
metadata:
name: hello
spec:
sidecar:
automountServiceAccountToken: false # 可选,是否挂载同名 SA 的 Token
container:
# 任意合法的 Kubernetes Container 定义
image: ...
name: ...
command: ...
ports:
- containerPort: 4355
securityContext: ...
resources:
requests: ...
limits: ...
注意 spec.sidecar 下有两个字段(见 pkg/plugins/spec/plugin_types.go):
automountServiceAccountToken(可选):若为 true,控制器会为插件挂载与插件同名的 ServiceAccount 的 Token 卷。container(必填):标准 Kubernetesv1.Container结构。
Validate() 强制要求以下三项,缺一不可,否则 argo executor-plugin build 会直接构建失败:
- 至少声明一个端口:
len(c.Ports) < 1报错"at least one port is mandatory"; - 必须设置资源请求与限制:
Resources.Requests/Resources.Limits为 nil 时报错; - 必须设置安全上下文:
SecurityContext == nil时报错。
这一设计初衷在官方文档中表述得很清楚:"我们把这些字段设为强制项,以确保任何人都不能创建一个占用不合理内存、或以 root 身份运行的 Executor Plugin,除非故意为之。"推荐的基准配置如下:
spec:
sidecar:
container:
resources:
requests:
cpu: 100m
memory: 32Mi
limits:
cpu: 200m
memory: 64Mi
securityContext:
runAsNonRoot: true
runAsUser: 1000
五、实战:构建一个 Python "Hello" Executor Plugin
下面按官方流程完整构建一个打印 "hello" 的 Python 插件(对应文档 docs/executor_plugins.md)。
前置条件
- 已在 Workflow Controller 上启用 Executor Plugin(见第三节);
- 已为 Agent Pod 配置额外 RBAC 权限——HTTP/Plugin 模板依赖 Argo Agent 执行,Agent 与控制器通过
WorkflowTaskSetCRD 通信,相关 RBAC 说明见 docs/http-template.md 的 "Argo Agent RBAC" 一节; - 一个作为主容器 sidecar 运行的 HTTP 服务器,按 docs/executor_swagger.md 描述的 RPC 契约响应来自 executor 的 HTTP 请求;
- 一份
plugin.yaml清单,最终转换为 ConfigMap 供控制器发现插件。
编写 HTTP 服务 server.py
插件需要响应 POST /api/v1/template.execute 请求。先用 curl 模拟一次调用(端口 4355 为示例端口):
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!"
}
}
将以下代码保存为 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()
这段示例代码体现了插件开发的核心约定:
- 只实现你需要的方法:返回 404 表示该方法不被支持,此后不会再被调用;
- URL 路径即 RPC 方法名:
/api/v1/template.execute对应template.execute方法; - 必须校验认证头:
Authorization头必须与/var/run/argo/token中的值一致,不一致返回 403(该 token 由控制器通过共享卷/var/run/argo挂载给每个插件 sidecar,路径常量定义于 workflow/common/common.go 的VarRunArgoPath,且只挂载当前插件的 token 子路径); - 请求体包含模板的输入参数:即
workflow元数据与template定义; - 响应体包含节点结果:可携带
phase(如Succeeded/Failed)、message以及outputs输出参数; - 返回
{}表示插件不处理该模板:例如某个 Slack 插件遇到 Tekton 模板时应返回{}而非报错; - 文件命名为
server.*会被自动复制到 sidecar 的args:这是 Python、Node.js 等脚本语言构建"自包含插件"的关键机制——build命令会把它读入容器args,从而无需额外挂载代码文件。
端口选择建议:端口号可任意,但不得与其他 Executor Plugin 冲突;不要使用 80、443、8080、8081、8443 等常见端口。若计划发布插件,请选择 10000 以下的一个随机端口并为插件提 PR;否则请使用大于 10000 的端口。
编写清单 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"
注意 command 中使用了 python -u -c,而脚本内容将由 build 命令自动填入 args。
构建、安装与验证
argo executor-plugin build .
kubectl -n argo apply -f hello-executor-plugin-configmap.yaml
检查控制器日志,确认插件已被发现:
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: { }
工作流将成功完成,节点消息为 Hello template!。
六、RPC 契约与底层调用链
请求与响应结构
template.execute 的请求体(ExecuteTemplateArgs)包含 workflow 与 template 两个必填字段,响应体(ExecuteTemplateReply)包含 node(节点结果)与 requeue(重新排队时长)两个可选字段,定义于 pkg/plugins/executor/template_executor_plugin.go:
type ExecuteTemplateArgs struct {
Workflow *Workflow `json:"workflow"`
Template *wfv1.Template `json:"template"`
}
type ExecuteTemplateReply struct {
Node *wfv1.NodeResult `json:"node,omitempty"`
Requeue *metav1.Duration `json:"requeue,omitempty"`
}
插件接口 TemplateExecutor 的 Swagger 路由注解为 POST /template.execute(basePath 为 /api/v1,详见 pkg/plugins/executor/swagger.yml),完整契约文档见 docs/executor_swagger.md。
Agent 如何调用插件
在 Agent 侧(workflow/executor/agent.go 的 executePluginTemplate),Agent 按顺序遍历全部插件,向每个插件发起 template.execute 调用;只要某个插件返回了 Node,就采纳该结果:若 phase 为 Succeeded 则任务完成,否则以返回的 requeue 时长延迟重试。若所有插件都未执行该模板,则报错 "no plugin executed the template"。
RPC 客户端封装在 workflow/executor/plugins/rpc/plugin.go,默认超时 30 秒,并使用指数退避重试(初始 1 秒、抖动 0.2、倍增因子 2、最多 5 步)。核心的 HTTP 调用与状态码处理位于 workflow/util/plugin/plugin.go:请求地址形如 http://<address>/api/v1/template.execute,请求头携带 Content-Type: application/json 与 Authorization: Bearer <token>。
状态码与失败语义
插件调用可能以多种方式失败,其语义如下(与客户端实现一一对应):
| 失败类型 | 判定 | 处理 |
|---|---|---|
| 连接错误 / Socket 错误 | 网络层异常 | 视为瞬时错误,按退避策略重试 |
| 超时 | 客户端 30 秒超时 | 视为瞬时错误,重试 |
| 404 | 方法不被插件支持 | 标记为无效方法,同一工作流内不再调用(invalid[method] = true) |
| 503 | 服务暂不可用 | 视为瞬时错误,重试 |
| 其他 4xx/5xx | — | 视为致命错误,不重试 |
瞬时错误会被重试,其余错误均为致命错误,最终导致对应步骤失败。
Re-Queue 机制
当插件需要异步等待长任务时,可以返回 Running/Pending 状态并附带一个重新排队时长,例如:
{
"node": {
"phase": "Running",
"message": "Long-running task started"
},
"requeue": "2m"
}
此时任务会被重新入队,template.execute 将在 2 分钟后被再次调用。Agent 侧通过 time.AfterFunc(requeue, ...) 实现定时重新入队,对应的测试用例见 workflow/executor/agent_test.go(覆盖了"执行成功后即使返回 requeue 也不重新排队"等边界行为)。
七、插件发现机制
工作流运行时,Executor Plugin 从以下两个位置加载(见 workflow/controller/agent.go 的 getExecutorPlugins):
- 工作流所在命名空间;
- Argo 安装命名空间(通常是
argo)。
控制器通过 Informer 监听带 workflows.argoproj.io/configmap-type: ExecutorPlugin 标签的 ConfigMap(逻辑见 workflow/controller/controller.go),并缓存为 executorPlugins[namespace][name] 映射。如果两个命名空间中存在同名插件,只加载工作流命名空间中的那一个(因为代码按命名空间顺序覆盖写入同一 name 键)。
由于插件本质上就是 ConfigMap,你也可以直接用 kubectl 列出所有已安装的插件:
kubectl get cm -l workflows.argoproj.io/configmap-type=ExecutorPlugin
八、Secrets:安全地接入第三方系统
与第三方系统交互时不可避免地需要密钥,但绝不能把它们写进 plugin.yaml。正确做法是通过 Kubernetes Secret 注入环境变量:
spec:
sidecar:
container:
env:
- name: URL
valueFrom:
secretKeyRef:
name: slack-executor-plugin
key: URL
Secret 的最佳实践与安全考量遵循 Kubernetes 官方文档规范(例如最小权限、Secret 轮换与加密等)。
九、调试与日志
插件运行在 Agent Pod 的 sidecar 容器中,日志与主容器相互独立,可通过容器名直接查看:
kubectl -n argo logs ${agentPodName} -c hello-executor-plugin
Agent Pod 名称格式为 <workflow-name>-agent(由 workflow/controller/agent.go 中的 woc.wf.NodeID("agent") + "-agent" 生成),并带有 workflows.argoproj.io/component: agent 标签以便通过 NetworkPolicy 等机制识别。
十、发布与社区生态
如果希望将插件分享给社区,请向 docs/plugin-directory.md 中的插件目录提交 Pull Request,将自己插件的名称与简介加入表格。目前社区已收录 Hello、Slack、Argo CD 同步、Volcano Job、Python、WASM、Chaos Mesh、AWS 服务、Pytorch Job、Ray Job 等多种 Executor Plugin,可作为实现参考与灵感来源。仓库自带的 examples/workflow-level-executor-plugin.yaml 与 test/e2e/manifests/plugins/workflow-controller-deployment.yaml 也提供了端到端的参考配置,配合 workflow/controller/agent_test.go 中的 TestWorkflowDefinedExecutorPluginsUsage 测试,可以进一步验证工作流级插件的加载、SA Token 自动挂载等行为。