Argo Workflows Executor 插件(Executor Plugin)开发实战:零改动扩展工作流引擎

原创2026-09-20 16:52:011,999 阅读
文章标签:工作流自动化云原生容器编排任务调度DevOps后端前端微服务机器学习

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:插件运行在控制器创建并管理的专用 agent Pod 中,每个正在运行的工作流只使用一个 Agent Pod。当多个步骤复用同一个插件时,这种架构能显著提升性能;同一个 Agent Pod 还会运行工作流中任何 HTTP 模板,带来额外的性能优势。

插件的定义方式是一个 ExecutorPlugin 自定义资源,普通用户和管理员都可以编写并安装它。从源码看,ExecutorPlugin 的载体其实是带特定标签的 ConfigMap——控制器通过 ConfigMap informer 动态发现插件,因此你可以随时增删插件而无需重启控制器(详见下文"控制器如何发现插件")。

与其他插件类型的分工

除了 Executor Plugin,Argo Workflows 还支持另一类扩展:

两者的定位截然不同: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):

  1. 为工作流创建一个名为 <workflow-node-id>-agent 的 Agent Pod(getAgentPodName,见 workflow/controller/agent.go);
  2. Agent Pod 由 init 容器(argoexec agent init)和 main 容器(argoexec agent main)组成,插件 sidecar 容器会与 main 容器一同调度进该 Pod(workflow/controller/agent.go);
  3. 控制器把插件地址列表(http://localhost:<port>)与插件名称列表通过环境变量注入 Agent(workflow/controller/agent.go);
  4. 插件 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 插件需要四样东西:

  1. 在 Workflow Controller 上启用 Executor 插件(见上文配置);
  2. 用于运行和管理 Agent Pod 的额外 RBAC 权限(见 docs/http-template.md 中关于 Agent Pod RBAC 的说明);
  3. 一个 HTTP 服务器,作为主容器的 sidecar 运行,按照 docs/executor_swagger.md 描述的 API 契约响应来自 executor 的 RPC 请求;
  4. 一个 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。

登录后查看全文
argo-workflows