Kubernetes Argo Workflows如何实战落地？从安装到编写完整工作流详解

Argo Workflows 是 CNCF 的毕业项目之一，专门为 Kubernetes 设计的容器原生工作流引擎。它把每一个任务步骤都放进独立容器中执行，天然继承了 Kubernetes 的调度、资源隔离和自动重试能力，目前在数据处理、机器学习流水线和 CI/CD 领域应用非常广泛。本文将从安装部署、核心概念、实际编写和踩坑经验几个方面，完整讲一遍如何在 Kubernetes 上把 Argo Workflows 真正用起来。

一、安装部署：两种方式的选择

最直接的方式是使用官方提供的安装清单，执行 kubectl create namespace argo 创建命名空间后，直接 apply 官方 manifest 即可。这种方式的好处是简单快速，所有资源一目了然，适合测试环境或想深入了解各组件构成的场景。

kubectl create namespace argo
kubectl apply -n argo -f https://github.com/argoproj/argo-workflows/releases/latest/download/install.yaml
kubectl get pods -n argo

另一种方式是使用 Helm 安装，适合需要精细控制参数的场景，比如自定义镜像仓库、配置 S3 作为制品存储等。Helm 的 values 文件可以把各类配置集中管理，便于版本化维护，这一点在生产环境中非常重要。

helm repo add argo https://argoproj.github.io/argo-helm
helm install argo-workflows argo/argo-workflows -n argo --create-namespace

安装完成后，官方 manifest 默认不需要认证就能访问 API Server，生产环境务必开启认证或者只在内网暴露。Argo Server 默认不对外暴露服务，本地调试可以用 port-forward 把 2746 端口转发出来，浏览器访问 UI 界面即可可视化查看工作流执行状态，这比反复 kubectl describe 直观得多。

二、核心概念：Workflow 与 Template 的关系

Argo Workflows 的一切都围绕两个核心对象展开。Workflow 是自定义资源（CRD），代表一次完整的工作流执行实例；Template 则是 Workflow 内部定义的任务单元，分为容器模板和控制器模板两类。容器模板真正执行计算，控制器模板负责编排逻辑，包括 Steps（分步执行）、DAG（有向无环图）、Script（脚本内嵌）和 Suspended（挂起等待）等。

理解这两者的关系是编写工作流的基础。一个 Workflow 的 spec.templates 字段里可以定义多个模板，入口模板通过 spec.entrypoint 指定。每个模板有自己的名字，控制器模板通过名字引用其他模板，形成调用链。这种设计让模板可以像函数一样被复用，配合参数传递机制，可以把一个通用的业务逻辑模板复用到几十条不同的流水线中。

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  generateName: hello-world-
spec:
  entrypoint: main
  templates:
  - name: main
    steps:
    - - name: step-1
        template: say-hello
        arguments:
          parameters:
          - name: message
            value: "来自第一个步骤"
  - name: say-hello
    inputs:
      parameters:
      - name: message
    container:
      image: busybox
      command: [echo]
      args: ["{{inputs.parameters.message}}"]

上面这个最小示例包含了三个要点：generateName 会自动追加随机后缀方便重复提交，entrypoint 指定入口，steps 中的双层短横线结构表达的是“一组并行任务”。这个结构初看容易搞混，后面会展开说明。

三、Steps 与 DAG：两种编排模式实战

Steps 模式按层级顺序执行，同一层的任务会并行运行，不同层之间串行。YAML 中的双层短横线不是笔误，外层列表的每一项是一个串行阶段，内层列表中的任务则是并行的。这个设计初学者经常写反，导致本想串行的任务全部并发执行。

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  generateName: steps-demo-
spec:
  entrypoint: main
  templates:
  - name: main
    steps:
    - - name: build
        template: task
        arguments:
          parameters: [{name: cmd, value: "构建阶段"}]
    - - name: test-a
        template: task
        arguments:
          parameters: [{name: cmd, value: "接口测试"}]
      - name: test-b
        template: task
        arguments:
          parameters: [{name: cmd, value: "性能测试"}]
    - - name: deploy
        template: task
        arguments:
          parameters: [{name: cmd, value: "发布上线"}]
  - name: task
    inputs:
      parameters:
      - name: cmd
    container:
      image: busybox
      command: [echo]
      args: ["{{inputs.parameters.cmd}}"]

DAG 模式则通过依赖关系定义执行顺序，比 Steps 更灵活。当任务之间的依赖关系复杂、存在多条并行链路时，DAG 的表达力明显更强。下面的例子中 A 先执行，B 和 C 在 A 完成后并行，D 等待 B 和 C 全部结束后才运行。

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  generateName: dag-demo-
spec:
  entrypoint: main
  templates:
  - name: main
    dag:
      tasks:
      - name: A
        template: task
      - name: B
        dependencies: [A]
        template: task
      - name: C
        dependencies: [A]
        template: task
      - name: D
        dependencies: [B, C]
        template: task
  - name: task
    container:
      image: alpine:3.18
      command: [sh, -c, "sleep 5 && echo done"]

DAG 还支持 when 字段做条件执行，例如 when: "{{tasks.A.status}} == Succeeded"，只有上游成功才继续。此外通过 depends 字段可以表达更细的依赖语义，比如 B.Failed 表示 B 失败时才触发，用于实现失败回滚或通知分支。

四、参数化、循环与制品传递

模板复用离不开参数化。除了 inputs 参数，Argo 还支持 withItems 循环，把一个模板展开成多个并行实例，处理批量任务非常方便，比如批量处理一组数据文件或一批镜像。

spec:
  entrypoint: main
  templates:
  - name: main
    steps:
    - - name: process
        template: worker
        withItems:
        - file1.csv
        - file2.csv
        - file3.csv
        arguments:
          parameters: [{name: file, value: "{{item}}"}]
  - name: worker
    inputs:
      parameters:
      - name: file
    container:
      image: busybox
      command: [echo]
      args: ["正在处理 {{inputs.parameters.file}}"]

任务之间的数据传递靠 Artifacts（制品）完成。一个任务把文件输出为制品，下游任务声明同名输入即可获取。制品默认存储在 Workflow Controller Pod 所在节点的本地目录，生产环境应配置 S3、MinIO 或 OSS 作为后端，通过 artifactRepository 配置指定。另外 withParam 可以配合脚本任务的 JSON 输出，实现动态数量的并行分支，这在“上一步生成任务清单、下一步并行消费”的场景中极为实用。

五、常见问题排查与生产建议

实战中最常见的几个问题值得提前了解。第一是 Pod 一直 Pending，多半是资源配额不足或镜像拉取失败，查看 Pod 事件能快速定位。第二是模板变量没被替换、原样出现在命令里，通常是变量拼写与参数名不一致导致。第三是制品上传失败，需要检查 artifact 仓库的凭证配置。排查时 kubectl logs -n argo deploy/workflow-controller 是最有用的命令，控制器日志会记录每次调度的细节。

生产环境还有几点建议：为 Workflow 配置 ttlStrategy 自动清理已完成的工作流，避免 etcd 数据膨胀；对不稳定的任务步骤设置 retryStrategy 实现自动重试；用 activeDeadlineSeconds 防止任务卡死占用资源；为不同业务设置 workflowTemplateRef 引用统一的 WorkflowTemplate，把流程定义与提交参数解耦。结合 Argo Events 还能实现 Git 提交或消息队列触发的全自动流水线，这套组合在机器学习平台建设中已经非常成熟。

总的来说，Argo Workflows 的上手门槛不高，核心在于吃透模板引用和参数传递机制，再根据业务复杂度选择 Steps 或 DAG。把上面的示例跑通之后，绝大多数批处理和流水线场景都能照葫芦画瓢迁移过来。

KubernetesArgo Workflows工作流编排修改时间：2026-09-13 22:01:02