Argo Workflows 完全实战指南#

1. Argo Workflows 简介#

1.1 什么是 Argo Workflows#

Argo Workflows 是一个开源的容器原生工作流引擎，用于在 Kubernetes 上编排并行任务。它通过 Kubernetes CRD（Custom Resource Definition）实现，是 CNCF 毕业项目。

官方文档：https://argo-workflows.readthedocs.io
源码地址：https://github.com/argoproj/argo-workflows

1.2 核心特性#

容器原生：每个工作流步骤都在容器中运行，无需传统 VM 环境的开销
DAG 支持：支持有向无环图（DAG）定义复杂的任务依赖关系
并行执行：自动并行执行独立任务，提升执行效率
工件管理：支持在步骤间传递文件和数据
参数化：支持工作流参数化，实现可复用的模板
条件执行：支持基于条件的分支执行
重试机制：内置失败重试和超时控制
可视化界面：提供直观的 Web UI 查看工作流执行状态

1.3 应用场景#

场景	说明	典型用例
CI/CD 流水线	构建、测试、部署自动化	代码编译、单元测试、镜像构建、部署发布
数据处理	批量数据处理和 ETL	数据清洗、转换、聚合、导入导出
机器学习	ML 模型训练和推理	数据预处理、模型训练、超参数调优、模型评估
基础设施自动化	集群管理和运维任务	备份恢复、资源清理、健康检查、批量操作

1.4 Argo Workflows vs 其他工作流引擎#

特性	Argo Workflows	Jenkins	Airflow
运行环境	Kubernetes 原生	独立服务器/容器	独立服务器/容器
定义方式	YAML（声明式）	Groovy/Pipeline（命令式）	Python（命令式）
容器支持	原生支持，每步骤一个容器	需要插件	需要 KubernetesExecutor
并行执行	自动并行	需要手动配置	支持，但配置复杂
可扩展性	基于 K8s，自动扩展	需要手动配置节点	需要配置 Worker
学习曲线	中等（需要了解 K8s）	低	中等（需要了解 Python）

2. 环境准备#

2.1 创建 Kind 集群#

在开始之前，我们需要一个实验环境。如果你没有现成的Kubernetes集群，可以基于kind搭建测试集群快速创建一个：

配置文件：

1
kind: Cluster
2
apiVersion: kind.x-k8s.io/v1alpha4
3
networking:
4
  apiServerAddress: "10.10.151.201"
5
nodes:
6
- role: control-plane
7
  extraPortMappings:
8
  - containerPort: 6443
9
    hostPort: 6443
10
    listenAddress: "10.10.151.201"
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. 安装 Argo Workflows#

3.1 使用 Helm 安装#

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]=*'

配置说明：

server.secure=false：禁用 HTTPS，使用 HTTP（测试环境）

--auth-mode=server：使用服务器模式认证（无需登录）

workflow.serviceAccount.create=true：自动创建工作流 ServiceAccount

workflow.serviceAccount.name=argo-workflow：ServiceAccount 名称

workflow.rbac.create=true：自动创建 RBAC 权限

workflow.rbac.rules[0]：给予工作流在 argo 命名空间的完整资源操作权限（测试环境）

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

1
# 下载 chart
2
helm pull argo/argo-workflows --version 0.47.4
3

4
# 从本地安装
5
helm upgrade --install argo-workflows ./argo-workflows-0.47.4.tgz \
6
  --namespace argo \
7
  --create-namespace \
8
  --set server.secure=false \
9
  --set server.extraArgs[0]="--auth-mode=server" \
10
  --set workflow.serviceAccount.create=true \
11
  --set workflow.serviceAccount.name=argo-workflow \
12
  --set workflow.rbac.create=true \
13
  --set 'workflow.rbac.rules[0].apiGroups[0]=' \
14
  --set 'workflow.rbac.rules[0].apiGroups[1]=apps' \
15
  --set 'workflow.rbac.rules[0].resources[0]=*' \
16
  --set 'workflow.rbac.rules[0].verbs[0]=*'

3.2 验证安装#

1
# 查看 Pod 状态
2
kubectl get pods -n argo -w

期望输出：

1
NAME                                                  READY   STATUS    RESTARTS   AGE
2
argo-workflows-server-695449f55-jbqvt                 1/1     Running   0          76s
3
argo-workflows-workflow-controller-858ff4bbc7-pjl9h   1/1     Running   0          76s

3.4 配置工件仓库（可选）#

如果需要在工作流步骤间传递文件（Artifacts），需要配置工件仓库。支持 S3、GCS、OSS 等对象存储。

使用 MinIO（本地测试）#

1
# 安装 MinIO（单节点模式，适合测试环境）
2
helm repo add minio https://charts.min.io/
3
helm install minio minio/minio \
4
  --namespace argo \
5
  --set mode=standalone \
6
  --set replicas=1 \
7
  --set persistence.enabled=false \
8
  --set rootUser=admin \
9
  --set rootPassword=password123 \
10
  --set resources.requests.memory=512Mi
11

12
# 创建 Secret
13
kubectl create secret generic minio-credentials -n argo \
14
  --from-literal=accesskey=admin \
15
  --from-literal=secretkey=password123
16

17
# 配置 Artifact Repository
18
kubectl apply -f - <<EOF
19
apiVersion: v1
20
kind: ConfigMap
21
metadata:
22
  name: artifact-repositories
23
  namespace: argo
24
data:
25
  default-v1: |
26
    s3:
27
      bucket: argo-artifacts
28
      endpoint: minio.argo.svc.cluster.local:9000
29
      insecure: true
30
      accessKeySecret:
31
        name: minio-credentials
32
        key: accesskey
33
      secretKeySecret:
34
        name: minio-credentials
35
        key: secretkey
36
EOF
37

38
# 创建 bucket
39
kubectl apply -f - <<EOF
40
apiVersion: batch/v1
41
kind: Job
42
metadata:
43
  name: minio-setup
44
  namespace: argo
45
spec:
46
  template:
47
    spec:
48
      restartPolicy: OnFailure
49
      containers:
50
      - name: mc
51
        image: minio/mc:latest
52
        command:
53
        - /bin/sh
54
        - -c
55
        - |
56
          mc alias set minio http://minio.argo.svc.cluster.local:9000 admin password123
57
          mc mb minio/argo-artifacts || true
58
          mc ls minio/
59
EOF
60

61
# 查看 Job 执行结果
62
kubectl wait --for=condition=complete --timeout=60s job/minio-setup -n argo
63
kubectl logs job/minio-setup -n argo
64

65
# 清理 Job
66
kubectl delete job minio-setup -n argo
67

68
# 配置 Workflow Controller 使用 Artifact Repository
69
kubectl patch configmap argo-workflows-workflow-controller-configmap -n argo --type merge -p '{
70
  "data": {
71
    "config": "nodeEvents:\n  enabled: true\nworkflowEvents:\n  enabled: true\nartifactRepository:\n  archiveLogs: false\n  s3:\n    bucket: argo-artifacts\n    endpoint: minio.argo.svc.cluster.local:9000\n    insecure: true\n    accessKeySecret:\n      name: minio-credentials\n      key: accesskey\n    secretKeySecret:\n      name: minio-credentials\n      key: secretkey\n"
72
  }
73
}'
74

75
# 等待 Workflow Controller 自动重启并加载配置
76
kubectl get pods -n argo -l app=workflow-controller -w

重要说明：

Workflow Controller 的 ConfigMap 中只能有一个 config 键

artifactRepository 配置必须放在 config 键的内容中

配置更新后，Workflow Controller 会自动重启

使用阿里云 OSS#

1
apiVersion: v1
2
kind: Secret
3
metadata:
4
  name: oss-credentials
5
  namespace: argo
6
type: Opaque
7
stringData:
8
  accessKey: YOUR_OSS_ACCESS_KEY_ID
9
  secretKey: YOUR_OSS_ACCESS_KEY_SECRET
10
---
11
apiVersion: v1
12
kind: ConfigMap
13
metadata:
14
  name: artifact-repositories
15
  namespace: argo
16
data:
17
  default-v1: |
18
    s3:
19
      bucket: argo-artifacts
20
      endpoint: oss-cn-hangzhou.aliyuncs.com
21
      insecure: false
22
      accessKeySecret:
23
        name: oss-credentials
24
        key: accessKey
25
      secretKeySecret:
26
        name: oss-credentials
27
        key: secretKey

说明：

endpoint：根据你的 OSS Bucket 所在地域修改，例如：

杭州：oss-cn-hangzhou.aliyuncs.com

北京：oss-cn-beijing.aliyuncs.com

上海：oss-cn-shanghai.aliyuncs.com

深圳：oss-cn-shenzhen.aliyuncs.com

bucket：替换为你的 OSS Bucket 名称

OSS 兼容 S3 协议，因此使用 s3 配置即可

4. 安装 Argo CLI#

macOS#

1
# 使用 Homebrew
2
brew install argo
3

4
# 或手动下载
5
ARGO_WORKFLOWS_VERSION=v3.7.10
6
curl -sLO https://github.com/argoproj/argo-workflows/releases/download/${ARGO_WORKFLOWS_VERSION}/argo-darwin-arm64.gz
7
gunzip argo-darwin-arm64.gz
8
chmod +x argo-darwin-arm64
9
sudo mv argo-darwin-arm64 /usr/local/bin/argo

Linux#

1
# 设置版本号（注意：这是 Argo Workflows 应用版本，不是 Helm chart 版本）
2
ARGO_WORKFLOWS_VERSION=v3.7.10
3

4
# 下载并安装
5
curl -sLO https://github.com/argoproj/argo-workflows/releases/download/${ARGO_WORKFLOWS_VERSION}/argo-linux-amd64.gz
6
gunzip argo-linux-amd64.gz
7
chmod +x argo-linux-amd64
8
sudo mv argo-linux-amd64 /usr/local/bin/argo

验证安装：

1
argo version

5. 访问 Argo Server UI#

Port Forward（测试环境）#

1
kubectl -n argo port-forward deployment/argo-workflows-server 2746:2746 --address 0.0.0.0

访问：http://localhost:2746 或 http://YOUR_HOST_IP:2746

6. 核心概念#

4.1 Workflow#

Workflow 是 Argo Workflows 的核心资源，定义了要执行的工作流。它具有双重职责：

定义工作流：描述工作流的结构和执行逻辑
存储状态：记录工作流的执行状态和结果

基本结构：

1
apiVersion: argoproj.io/v1alpha1
2
kind: Workflow
3
metadata:
4
  generateName: hello-world-  # 使用 generateName 自动生成唯一名称
5
spec:
6
  serviceAccountName: argo-workflow
7
  entrypoint: main  # 入口模板
8
  templates:
9
  - name: main
10
    container:
11
      image: busybox
12
      command: [echo]
13
      args: ["Hello World"]

4.2 Template 类型#

Argo Workflows 提供 9 种模板类型，分为两大类：

模板定义类（Template Definitions）#

定义实际要执行的工作：

类型	说明	使用场景
Container	运行容器	执行命令、运行应用
Script	运行脚本	Python/Bash 脚本执行
Resource	操作 K8s 资源	创建/删除/更新资源
Suspend	暂停执行	人工审批、等待条件
HTTP	发送 HTTP 请求	调用 API、Webhook
Plugin	执行插件	扩展功能
Container Set	运行多容器	需要多容器协作的任务

模板调用类（Template Invocators）#

控制工作流执行逻辑：

类型	说明	使用场景
Steps	顺序执行步骤	线性流程、多阶段任务
DAG	有向无环图	复杂依赖关系、并行任务

4.3 参数（Parameters）#

参数用于在模板间传递数据：

1
spec:
2
  arguments:
3
    parameters:
4
    - name: message
5
      value: "Hello Argo"
6
  templates:
7
  - name: print-message
8
    inputs:
9
      parameters:
10
      - name: message
11
    container:
12
      image: busybox
13
      command: [echo]
14
      args: ["{{inputs.parameters.message}}"]

4.4 工件（Artifacts）#

工件用于在步骤间传递文件：

1
templates:
2
- name: generate-artifact
3
  container:
4
    image: busybox
5
    command: [sh, -c]
6
    args: ["echo 'hello world' > /tmp/hello.txt"]
7
  outputs:
8
    artifacts:
9
    - name: hello-art
10
      path: /tmp/hello.txt
11

12
- name: consume-artifact
13
  inputs:
14
    artifacts:
15
    - name: hello-art
16
      path: /tmp/hello.txt
17
  container:
18
    image: busybox
19
    command: [cat]
20
    args: ["/tmp/hello.txt"]

7. 实战案例#

7.1 案例 1：Hello World#

最简单的工作流示例：

1
apiVersion: argoproj.io/v1alpha1
2
kind: Workflow
3
metadata:
4
  generateName: hello-world-
5
spec:
6
  serviceAccountName: argo-workflow
7
  entrypoint: main
8
  templates:
9
  - name: main
10
    container:
11
      image: busybox
12
      command: [echo]
13
      args: ["Hello World"]

提交工作流：

1
# 使用 kubectl
2
kubectl create -f hello-world.yaml -n argo
3

4
# 使用 argo CLI
5
argo submit hello-world.yaml -n argo --watch
6

7
# 查看日志
8
argo logs @latest -n argo

7.2 案例 2：Steps 顺序执行#

使用 Steps 实现多步骤顺序执行：

1
apiVersion: argoproj.io/v1alpha1
2
kind: Workflow
3
metadata:
4
  generateName: steps-
5
spec:
6
  serviceAccountName: argo-workflow
7
  entrypoint: main
8
  templates:
9
  - name: main
10
    steps:
11
    - - name: step1
12
        template: echo
13
        arguments:
14
          parameters:
15
          - name: message
16
            value: "Step 1"
17
    - - name: step2a
18
        template: echo
19
        arguments:
20
          parameters:
21
          - name: message
22
            value: "Step 2a"
23
      - name: step2b
24
        template: echo
25
        arguments:
26
          parameters:
27
          - name: message
28
            value: "Step 2b"
29
    - - name: step3
30
        template: echo
31
        arguments:
32
          parameters:
33
          - name: message
34
            value: "Step 3"
35

36
  - name: echo
37
    inputs:
38
      parameters:
39
      - name: message
40
    container:
41
      image: busybox
42
      command: [echo]
43
      args: ["{{inputs.parameters.message}}"]

执行流程：

Step 1 执行
Step 2a 和 Step 2b 并行执行
Step 3 执行

提交工作流：

1
argo submit steps-workflow.yaml -n argo --watch

期望类似的最终结果：

1
Name:                steps-fsc4w
2
Namespace:           argo
3
ServiceAccount:      argo-workflow
4
Status:              Succeeded
5
Conditions:
6
 PodRunning          False
7
 Completed           True
8
Created:             Wed Mar 04 11:17:23 +0800 (56 seconds ago)
9
Started:             Wed Mar 04 11:17:23 +0800 (56 seconds ago)
10
Finished:            Wed Mar 04 11:18:19 +0800 (now)
11
Duration:            56 seconds
12
Progress:            4/4
13
ResourcesDuration:   0s*(1 cpu),20s*(100Mi memory)
14

15
STEP            TEMPLATE  PODNAME                      DURATION  MESSAGE
16
 ✔ steps-fsc4w  main
17
 ├───✔ step1    echo      steps-fsc4w-echo-3409550729  4s
18
 ├─┬─✔ step2a   echo      steps-fsc4w-echo-454416900   4s
19
 │ └─✔ step2b   echo      steps-fsc4w-echo-504749757   33s
20
 └───✔ step3    echo      steps-fsc4w-echo-3563388113  5s

7.3 案例 3：DAG 并行执行#

使用 DAG 定义复杂的依赖关系：

1
apiVersion: argoproj.io/v1alpha1
2
kind: Workflow
3
metadata:
4
  generateName: dag-
5
spec:
6
  serviceAccountName: argo-workflow
7
  entrypoint: main
8
  templates:
9
  - name: main
10
    dag:
11
      tasks:
12
      - name: A
13
        template: echo
14
        arguments:
15
          parameters:
16
          - name: message
17
            value: "Task A"
18

19
      - name: B
20
        dependencies: [A]
21
        template: echo
22
        arguments:
23
          parameters:
24
          - name: message
25
            value: "Task B"
26

27
      - name: C
28
        dependencies: [A]
29
        template: echo
30
        arguments:
31
          parameters:
32
          - name: message
33
            value: "Task C"
34

35
      - name: D
36
        dependencies: [B, C]
37
        template: echo
38
        arguments:
39
          parameters:
40
          - name: message
41
            value: "Task D"
42

43
  - name: echo
44
    inputs:
45
      parameters:
46
      - name: message
47
    container:
48
      image: busybox
49
      command: [echo]
50
      args: ["{{inputs.parameters.message}}"]

执行流程：

提交工作流：

1
argo submit dag-workflow.yaml -n argo --watch

7.4 案例 4：脚本执行#

使用 Script 模板执行 Python 脚本：

1
apiVersion: argoproj.io/v1alpha1
2
kind: Workflow
3
metadata:
4
  generateName: script-
5
spec:
6
  serviceAccountName: argo-workflow
7
  entrypoint: main
8
  templates:
9
  - name: main
10
    steps:
11
    - - name: generate
12
        template: gen-random-int
13
    - - name: print
14
        template: print-message
15
        arguments:
16
          parameters:
17
          - name: message
18
            value: "{{steps.generate.outputs.result}}"
19

20
  - name: gen-random-int
21
    script:
22
      image: python:alpine3.23
23
      command: [python]
24
      source: |
25
        import random
26
        i = random.randint(1, 100)
27
        print(i)
28

29
  - name: print-message
30
    inputs:
31
      parameters:
32
      - name: message
33
    container:
34
      image: busybox
35
      command: [echo]
36
      args: ["Random number: {{inputs.parameters.message}}"]

提交工作流：

1
argo submit script-workflow.yaml -n argo --watch

期望类似的最终结果：

1
Name:                dag-bhp6s
2
Namespace:           argo
3
ServiceAccount:      argo-workflow
4
Status:              Succeeded
5
Conditions:
6
 PodRunning          False
7
 Completed           True
8
Created:             Wed Mar 04 11:20:08 +0800 (30 seconds ago)
9
Started:             Wed Mar 04 11:20:08 +0800 (30 seconds ago)
10
Finished:            Wed Mar 04 11:20:38 +0800 (now)
11
Duration:            30 seconds
12
Progress:            4/4
13
ResourcesDuration:   19s*(100Mi memory),0s*(1 cpu)
14

15
STEP          TEMPLATE  PODNAME                    DURATION  MESSAGE
16
 ✔ dag-bhp6s  main
17
 ├─✔ A        echo      dag-bhp6s-echo-1335943234  4s
18
 ├─✔ B        echo      dag-bhp6s-echo-1319165615  4s
19
 ├─✔ C        echo      dag-bhp6s-echo-1302387996  5s
20
 └─✔ D        echo      dag-bhp6s-echo-1285610377  4s

7.5 案例 5：工件传递#

在步骤间传递文件。

前置条件：工件传递需要配置 Artifact Repository，请先完成 3.4 节的 MinIO 配置。

1
apiVersion: argoproj.io/v1alpha1
2
kind: Workflow
3
metadata:
4
  generateName: artifact-
5
spec:
6
  serviceAccountName: argo-workflow
7
  entrypoint: main
8
  templates:
9
  - name: main
10
    steps:
11
    - - name: generate
12
        template: generate-file
13
    - - name: consume
14
        template: consume-file
15
        arguments:
16
          artifacts:
17
          - name: input-file
18
            from: "{{steps.generate.outputs.artifacts.output-file}}"
19

20
  - name: generate-file
21
    container:
22
      image: busybox
23
      command: [sh, -c]
24
      args: ["echo 'Hello from artifact' > /tmp/output.txt"]
25
    outputs:
26
      artifacts:
27
      - name: output-file
28
        path: /tmp/output.txt
29

30
  - name: consume-file
31
    inputs:
32
      artifacts:
33
      - name: input-file
34
        path: /tmp/input.txt
35
    container:
36
      image: busybox
37
      command: [cat]
38
      args: ["/tmp/input.txt"]

提交工作流：

1
argo submit artifact-workflow.yaml -n argo --watch

期望类似的最终结果：

1
Name:                artifact-t69b6
2
Namespace:           argo
3
ServiceAccount:      argo-workflow
4
Status:              Succeeded
5
Conditions:
6
 PodRunning          False
7
 Completed           True
8
Created:             Wed Mar 04 11:35:08 +0800 (20 seconds ago)
9
Started:             Wed Mar 04 11:35:08 +0800 (20 seconds ago)
10
Finished:            Wed Mar 04 11:35:28 +0800 (now)
11
Duration:            20 seconds
12
Progress:            2/2
13
ResourcesDuration:   0s*(1 cpu),8s*(100Mi memory)
14

15
STEP               TEMPLATE       PODNAME                                 DURATION  MESSAGE
16
 ✔ artifact-t69b6  main
17
 ├───✔ generate    generate-file  artifact-t69b6-generate-file-149832164  4s
18
 └───✔ consume     consume-file   artifact-t69b6-consume-file-3273100530  4s

7.6 案例 6：条件执行#

基于条件执行不同的分支：

1
apiVersion: argoproj.io/v1alpha1
2
kind: Workflow
3
metadata:
4
  generateName: conditional-
5
spec:
6
  serviceAccountName: argo-workflow
7
  entrypoint: main
8
  arguments:
9
    parameters:
10
    - name: environment
11
      value: "production"
12

13
  templates:
14
  - name: main
15
    steps:
16
    - - name: check-env
17
        template: check-environment
18

19
    - - name: prod-deploy
20
        template: deploy
21
        arguments:
22
          parameters:
23
          - name: env
24
            value: "production"
25
        when: "{{steps.check-env.outputs.result}} == production"
26

27
      - name: dev-deploy
28
        template: deploy
29
        arguments:
30
          parameters:
31
          - name: env
32
            value: "development"
33
        when: "{{steps.check-env.outputs.result}} != production"
34

35
  - name: check-environment
36
    script:
37
      image: python:alpine3.23
38
      command: [python]
39
      source: |
40
        print("{{workflow.parameters.environment}}")
41

42
  - name: deploy
43
    inputs:
44
      parameters:
45
      - name: env
46
    container:
47
      image: busybox
48
      command: [echo]
49
      args: ["Deploying to {{inputs.parameters.env}}"]

提交工作流：

1
# 生产环境
2
argo submit conditional-workflow.yaml -n argo -p environment=production --watch
3

4
# 开发环境
5
argo submit conditional-workflow.yaml -n argo -p environment=development --watch

生产环境期望类似的最终结果：

1
Name:                conditional-ltr9x
2
Namespace:           argo
3
ServiceAccount:      argo-workflow
4
Status:              Succeeded
5
Conditions:
6
 PodRunning          False
7
 Completed           True
8
Created:             Wed Mar 04 11:42:20 +0800 (34 seconds ago)
9
Started:             Wed Mar 04 11:42:20 +0800 (34 seconds ago)
10
Finished:            Wed Mar 04 11:42:54 +0800 (now)
11
Duration:            34 seconds
12
Progress:            2/2
13
ResourcesDuration:   1s*(1 cpu),18s*(100Mi memory)
14
Parameters:
15
  environment:       production
16

17
STEP                  TEMPLATE           PODNAME                                        DURATION  MESSAGE
18
 ✔ conditional-ltr9x  main
19
 ├───✔ check-env      check-environment  conditional-ltr9x-check-environment-504116037  14s
20
 └─┬─○ dev-deploy     deploy                                                                      when 'production != production' evaluated false
21
   └─✔ prod-deploy    deploy             conditional-ltr9x-deploy-754292413             4s

测试环境期望类似的最终结果：

1
Name:                conditional-px5t2
2
Namespace:           argo
3
ServiceAccount:      argo-workflow
4
Status:              Succeeded
5
Conditions:
6
 PodRunning          False
7
 Completed           True
8
Created:             Wed Mar 04 11:43:19 +0800 (30 seconds ago)
9
Started:             Wed Mar 04 11:43:19 +0800 (30 seconds ago)
10
Finished:            Wed Mar 04 11:43:49 +0800 (now)
11
Duration:            30 seconds
12
Progress:            2/2
13
ResourcesDuration:   1s*(1 cpu),19s*(100Mi memory)
14
Parameters:
15
  environment:       development
16

17
STEP                  TEMPLATE           PODNAME                                         DURATION  MESSAGE
18
 ✔ conditional-px5t2  main
19
 ├───✔ check-env      check-environment  conditional-px5t2-check-environment-1115641911  16s
20
 └─┬─✔ dev-deploy     deploy             conditional-px5t2-deploy-12024433               5s
21
   └─○ prod-deploy    deploy

7.7 案例 7：重试机制#

配置失败重试：

1
apiVersion: argoproj.io/v1alpha1
2
kind: Workflow
3
metadata:
4
  generateName: retry-
5
spec:
6
  serviceAccountName: argo-workflow
7
  entrypoint: main
8
  templates:
9
  - name: main
10
    retryStrategy:
11
      limit: "3"
12
      retryPolicy: "Always"
13
      backoff:
14
        duration: "5s"
15
        factor: 2
16
        maxDuration: "1m"
17
    container:
18
      image: python:alpine3.23
19
      command: [python]
20
      args:
21
      - -c
22
      - |
23
        import random
24
        import sys
25
        # 70% 概率失败
26
        if random.random() < 0.7:
27
          print("Task failed!")
28
          sys.exit(1)
29
        else:
30
          print("Task succeeded!")

提交工作流：

1
argo submit retry-workflow.yaml -n argo --watch

期望类似的最终结果：

1
Name:                retry-cf29c
2
Namespace:           argo
3
ServiceAccount:      argo-workflow
4
Status:              Succeeded
5
Conditions:
6
 PodRunning          False
7
 Completed           True
8
Created:             Wed Mar 04 11:44:21 +0800 (10 seconds ago)
9
Started:             Wed Mar 04 11:44:21 +0800 (10 seconds ago)
10
Finished:            Wed Mar 04 11:44:31 +0800 (now)
11
Duration:            10 seconds
12
Progress:            1/1
13
ResourcesDuration:   0s*(1 cpu),4s*(100Mi memory)
14

15
STEP               TEMPLATE  PODNAME                     DURATION  MESSAGE
16
 ✔ retry-cf29c(0)  main      retry-cf29c-main-439993472  4s

7.8 案例 8：CI/CD 流水线#

使用真实的开源项目演示 CI/CD 流水线。本示例使用 flask-hello-world 项目进行代码检出、测试和部署。

注：为了方便，部署在了argo namespace下

1
apiVersion: argoproj.io/v1alpha1
2
kind: Workflow
3
metadata:
4
  generateName: cicd-pipeline-
5
spec:
6
  serviceAccountName: argo-workflow
7
  entrypoint: main
8
  arguments:
9
    parameters:
10
    - name: repo
11
      value: "https://github.com/pallets/flask.git"
12
    - name: branch
13
      value: "main"
14
    - name: app-name
15
      value: "flask-demo"
16

17
  volumeClaimTemplates:
18
  - metadata:
19
      name: workdir
20
    spec:
21
      accessModes: [ "ReadWriteOnce" ]
22
      resources:
23
        requests:
24
          storage: 500Mi
25

26
  templates:
27
  - name: main
28
    steps:
29
    - - name: checkout
30
        template: git-clone
31

32
    - - name: lint
33
        template: run-lint
34

35
    - - name: test
36
        template: run-tests
37

38
    - - name: deploy
39
        template: deploy-app
40

41
  - name: git-clone
42
    container:
43
      image: alpine/git
44
      command: [sh, -c]
45
      args:
46
      - |
47
        git clone -b {{workflow.parameters.branch}} --depth 1 {{workflow.parameters.repo}} /work/repo
48
        cd /work/repo
49
        echo "Cloned repository: {{workflow.parameters.repo}}"
50
        echo "Branch: {{workflow.parameters.branch}}"
51
        echo "Commit: $(git rev-parse HEAD)"
52
      volumeMounts:
53
      - name: workdir
54
        mountPath: /work
55

56
  - name: run-lint
57
    container:
58
      image: python:3.11-slim
59
      command: [sh, -c]
60
      args:
61
      - |
62
        cd /work/repo
63
        pip install --quiet flake8
64
        echo "Running code linting..."
65
        flake8 src/flask --count --select=E9,F63,F7,F82 --show-source --statistics || true
66
        echo "Linting completed"
67
      volumeMounts:
68
      - name: workdir
69
        mountPath: /work
70

71
  - name: run-tests
72
    container:
73
      image: python:3.11-slim
74
      command: [sh, -c]
75
      args:
76
      - |
77
        cd /work/repo
78
        pip install --quiet -e .
79
        pip install --quiet pytest
80
        echo "Running tests..."
81
        pytest tests/ -v || echo "Tests completed with some failures (demo purpose)"
82
      volumeMounts:
83
      - name: workdir
84
        mountPath: /work
85

86
  - name: deploy-app
87
    resource:
88
      action: apply
89
      manifest: |
90
        apiVersion: v1
91
        kind: ConfigMap
92
        metadata:
93
          name: {{workflow.parameters.app-name}}-config
94
          namespace: argo
95
        data:
96
          app.info: |
97
            Application: {{workflow.parameters.app-name}}
98
            Repository: {{workflow.parameters.repo}}
99
            Branch: {{workflow.parameters.branch}}
100
            Deployed: $(date)

提交工作流：

1
# 使用默认参数
2
argo submit cicd-pipeline.yaml -n argo --watch
3

4
# 或指定自定义参数
5
argo submit cicd-pipeline.yaml -n argo \
6
  -p repo=https://github.com/pallets/flask.git \
7
  -p branch=main \
8
  -p app-name=my-flask-app \
9
  --watch

期望类似的最终结果：

1
Name:                cicd-pipeline-pfg6f
2
Namespace:           argo
3
ServiceAccount:      argo-workflow
4
Status:              Succeeded
5
Conditions:
6
 PodRunning          False
7
 Completed           True
8
Created:             Wed Mar 04 12:35:31 +0800 (2 minutes ago)
9
Started:             Wed Mar 04 12:35:31 +0800 (2 minutes ago)
10
Finished:            Wed Mar 04 12:37:53 +0800 (now)
11
Duration:            2 minutes 22 seconds
12
Progress:            4/4
13
ResourcesDuration:   5s*(1 cpu),1m15s*(100Mi memory)
14
Parameters:
15
  repo:              https://github.com/pallets/flask.git
16
  branch:            main
17
  app-name:          flask-demo
18

19
STEP                    TEMPLATE    PODNAME                                    DURATION  MESSAGE
20
 ✔ cicd-pipeline-pfg6f  main
21
 ├───✔ checkout         git-clone   cicd-pipeline-pfg6f-git-clone-2106511117   47s
22
 ├───✔ lint             run-lint    cicd-pipeline-pfg6f-run-lint-717278403     26s
23
 ├───✔ test             run-tests   cicd-pipeline-pfg6f-run-tests-655980579    14s
24
 └───✔ deploy           deploy-app  cicd-pipeline-pfg6f-deploy-app-2393920939  26s

验证部署结果：

1
# 查看创建的 ConfigMap
2
kubectl get configmap flask-demo-config -n argo -o yaml

8. WorkflowTemplate 可复用模板#

WorkflowTemplate 允许定义可复用的工作流模板，便于在多个工作流中重复使用相同的逻辑。本示例使用 gin-gonic/gin 项目演示模板的创建和使用。

8.1 创建 WorkflowTemplate#

1
apiVersion: argoproj.io/v1alpha1
2
kind: WorkflowTemplate
3
metadata:
4
  name: go-build-test
5
  namespace: argo
6
spec:
7
  serviceAccountName: argo-workflow
8
  entrypoint: main
9
  arguments:
10
    parameters:
11
    - name: repo
12
      value: "https://github.com/gin-gonic/gin.git"
13
    - name: branch
14
      value: "master"
15

16
  volumes:
17
  - name: workdir
18
    emptyDir: {}
19

20
  templates:
21
  - name: main
22
    steps:
23
    - - name: checkout
24
        template: git-clone
25

26
    - - name: build
27
        template: go-build
28

29
    - - name: test
30
        template: go-test
31

32
  - name: git-clone
33
    container:
34
      image: alpine/git
35
      command: [sh, -c]
36
      args:
37
      - |
38
        git clone -b {{workflow.parameters.branch}} --depth 1 {{workflow.parameters.repo}} /work/repo
39
        cd /work/repo
40
        echo "Repository: {{workflow.parameters.repo}}"
41
        echo "Branch: {{workflow.parameters.branch}}"
42
        echo "Commit: $(git rev-parse HEAD)"
43
      volumeMounts:
44
      - name: workdir
45
        mountPath: /work
46

47
  - name: go-build
48
    container:
49
      image: golang:1.21-alpine
50
      command: [sh, -c]
51
      args:
52
      - |
53
        cd /work/repo
54
        echo "Building Go project..."
55
        go build -v ./...
56
        echo "Build completed successfully"
57
      volumeMounts:
58
      - name: workdir
59
        mountPath: /work
60

61
  - name: go-test
62
    container:
63
      image: golang:1.21-alpine
64
      command: [sh, -c]
65
      args:
66
      - |
67
        cd /work/repo
68
        echo "Running Go tests..."
69
        go test -v ./... -short
70
        echo "Tests completed"
71
      volumeMounts:
72
      - name: workdir
73
        mountPath: /work

创建模板：

1
kubectl apply -f workflow-template.yaml

验证模板创建：

1
# 查看 WorkflowTemplate
2
kubectl get workflowtemplate -n argo
3

4
# 查看详细信息
5
kubectl describe workflowtemplate go-build-test -n argo

8.2 使用 WorkflowTemplate#

使用默认参数运行模板：

1
# 直接从 WorkflowTemplate 提交工作流
2
argo submit --from workflowtemplate/go-build-test -n argo --watch

使用自定义参数运行模板：

1
# 使用不同的分支
2
argo submit --from workflowtemplate/go-build-test -n argo \
3
  -p branch=v1.9.1 \
4
  --watch

或者通过 YAML 文件引用模板：

1
apiVersion: argoproj.io/v1alpha1
2
kind: Workflow
3
metadata:
4
  generateName: use-go-template-
5
spec:
6
  serviceAccountName: argo-workflow
7
  workflowTemplateRef:
8
    name: go-build-test
9
  arguments:
10
    parameters:
11
    - name: repo
12
      value: "https://github.com/gin-gonic/gin.git"
13
    - name: branch
14
      value: "master"

提交工作流：

1
argo submit use-workflow-template.yaml -n argo --watch

期望类似的最终结果：

1
Name:                go-build-test-r89hh
2
Namespace:           argo
3
ServiceAccount:      argo-workflow
4
Status:              Succeeded
5
Conditions:
6
 PodRunning          False
7
 Completed           True
8
Created:             Wed Mar 04 12:52:22 +0800 (1 minute ago)
9
Started:             Wed Mar 04 12:52:22 +0800 (1 minute ago)
10
Finished:            Wed Mar 04 12:53:38 +0800 (now)
11
Duration:            1 minute 16 seconds
12
Progress:            3/3
13
ResourcesDuration:   56s*(100Mi memory),4s*(1 cpu)
14
Parameters:
15
  repo:              https://github.com/gin-gonic/gin.git
16
  branch:            master
17

18
STEP                    TEMPLATE   PODNAME                                   DURATION  MESSAGE
19
 ✔ go-build-test-r89hh  main
20
 ├───✔ checkout         git-clone  go-build-test-r89hh-git-clone-1757181677  5s
21
 ├───✔ build            go-build   go-build-test-r89hh-go-build-3721440394   47s
22
 └───✔ test             go-test    go-build-test-r89hh-go-test-2594344963    4s

9. CronWorkflow 定时任务#

9.1 创建 CronWorkflow#

1
apiVersion: argoproj.io/v1alpha1
2
kind: CronWorkflow
3
metadata:
4
  name: backup-daily
5
  namespace: argo
6
spec:
7
  schedule: "0 13 * * *"  # 每天 13 点执行
8
  timezone: "Asia/Shanghai"
9
  concurrencyPolicy: "Replace"  # Replace, Allow, Forbid
10
  startingDeadlineSeconds: 0
11
  successfulJobsHistoryLimit: 3
12
  failedJobsHistoryLimit: 1
13

14
  workflowSpec:
15
    entrypoint: backup
16
    templates:
17
    - name: backup
18
      steps:
19
      - - name: database-backup
20
          template: backup-db
21
      - - name: upload-to-s3
22
          template: upload-backup
23

24
    - name: backup-db
25
      container:
26
        image: postgres:15
27
        command: [sh, -c]
28
        args:
29
        - |
30
          pg_dump -h postgres-host -U postgres mydb > /backup/backup.sql
31
        volumeMounts:
32
        - name: backup-volume
33
          mountPath: /backup
34

35
    - name: upload-backup
36
      container:
37
        image: amazon/aws-cli
38
        command: [sh, -c]
39
        args:
40
        - |
41
          aws s3 cp /backup/backup.sql s3://my-bucket/backups/$(date +%Y%m%d).sql
42
        volumeMounts:
43
        - name: backup-volume
44
          mountPath: /backup
45

46
    volumeClaimTemplates:
47
    - metadata:
48
        name: backup-volume
49
      spec:
50
        accessModes: [ "ReadWriteOnce" ]
51
        resources:
52
          requests:
53
            storage: 10Gi

创建定时任务：

1
kubectl apply -f cron-workflow.yaml

9.2 管理 CronWorkflow#

1
# 查看所有 CronWorkflow
2
kubectl get cronworkflow -n argo
3

4
# 查看详情
5
kubectl describe cronworkflow backup-daily -n argo
6

7
# 暂停 CronWorkflow
8
kubectl patch cronworkflow backup-daily -n argo -p '{"spec":{"suspend":true}}'
9

10
# 恢复 CronWorkflow
11
kubectl patch cronworkflow backup-daily -n argo -p '{"spec":{"suspend":false}}'
12

13
# 删除 CronWorkflow
14
kubectl delete cronworkflow backup-daily -n argo

10. 常用命令#

10.1 Workflow 管理#

1
# 提交工作流
2
argo submit workflow.yaml -n argo
3

4
# 提交并观察
5
argo submit workflow.yaml -n argo --watch
6

7
# 提交并传递参数
8
argo submit workflow.yaml -n argo -p param1=value1 -p param2=value2
9

10
# 列出工作流
11
argo list -n argo
12

13
# 查看工作流详情
14
argo get <workflow-name> -n argo
15

16
# 查看工作流日志
17
argo logs <workflow-name> -n argo
18

19
# 查看最新工作流日志
20
argo logs @latest -n argo
21

22
# 删除工作流
23
argo delete <workflow-name> -n argo
24

25
# 删除所有已完成的工作流
26
argo delete --completed -n argo
27

28
# 重新提交工作流
29
argo resubmit <workflow-name> -n argo
30

31
# 重试失败的工作流
32
argo retry <workflow-name> -n argo
33

34
# 暂停工作流
35
argo suspend <workflow-name> -n argo
36

37
# 恢复工作流
38
argo resume <workflow-name> -n argo
39

40
# 终止工作流
41
argo terminate <workflow-name> -n argo
42

43
# 停止工作流
44
argo stop <workflow-name> -n argo

10.2 使用 kubectl 管理#

1
# 查看工作流
2
kubectl get workflow -n argo
3

4
# 查看工作流详情
5
kubectl describe workflow <workflow-name> -n argo
6

7
# 查看工作流 YAML
8
kubectl get workflow <workflow-name> -n argo -o yaml
9

10
# 删除工作流
11
kubectl delete workflow <workflow-name> -n argo
12

13
# 查看 WorkflowTemplate
14
kubectl get workflowtemplate -n argo
15

16
# 查看 CronWorkflow
17
kubectl get cronworkflow -n argo

11. 常见问题排查#

11.1 工作流一直处于 Pending 状态#

原因：

资源不足（CPU/内存）
镜像拉取失败
PVC 无法挂载

排查步骤：

1
# 查看工作流详情
2
argo get <workflow-name> -n argo
3

4
# 查看 Pod 状态
5
kubectl get pods -n argo -l workflows.argoproj.io/workflow=<workflow-name>
6

7
# 查看 Pod 详情
8
kubectl describe pod <pod-name> -n argo
9

10
# 查看 Pod 事件
11
kubectl get events -n argo --field-selector involvedObject.name=<pod-name>

解决方案：

增加集群资源
检查镜像地址和拉取凭证
检查 StorageClass 配置

11.2 工作流执行失败#

原因：

容器执行错误
超时
资源限制

排查步骤：

1
# 查看工作流日志
2
argo logs <workflow-name> -n argo
3

4
# 查看特定步骤日志
5
argo logs <workflow-name> -n argo -c <step-name>
6

7
# 查看工作流状态
8
kubectl get workflow <workflow-name> -n argo -o jsonpath='{.status.phase}'

解决方案：

检查容器日志，修复代码错误
调整超时时间
增加资源限制

11.3 工件传递失败#

原因：

Artifact Repository 未配置
S3 凭证错误
网络问题

排查步骤：

1
# 查看 Artifact Repository 配置
2
kubectl get configmap artifact-repositories -n argo -o yaml
3

4
# 查看工作流日志
5
argo logs <workflow-name> -n argo

解决方案：

配置正确的 Artifact Repository
验证 S3 凭证
检查网络连通性

11.4 权限问题#

原因：

ServiceAccount 权限不足
RBAC 配置错误

排查步骤：

1
# 查看 ServiceAccount
2
kubectl get sa -n argo
3

4
# 查看 RoleBinding
5
kubectl get rolebinding -n argo
6

7
# 查看工作流使用的 ServiceAccount
8
kubectl get workflow <workflow-name> -n argo -o jsonpath='{.spec.serviceAccountName}'

解决方案：

创建正确的 ServiceAccount 和 RBAC 规则
在工作流中指定 ServiceAccount

12. 最佳实践#

12.1 资源管理#

设置资源限制：

1
templates:
2
- name: resource-limited
3
  container:
4
    image: busybox
5
    command: [sh, -c]
6
    args: ["echo 'Running with resource limits'"]
7
    resources:
8
      requests:
9
        memory: "64Mi"
10
        cpu: "250m"
11
      limits:
12
        memory: "128Mi"
13
        cpu: "500m"

使用节点选择器：

1
templates:
2
- name: gpu-task
3
  container:
4
    image: tensorflow/tensorflow:latest-gpu
5
    command: [python, train.py]
6
  nodeSelector:
7
    gpu: "true"
8
  tolerations:
9
  - key: "nvidia.com/gpu"
10
    operator: "Exists"
11
    effect: "NoSchedule"

12.2 安全最佳实践#

使用专用 ServiceAccount：

1
spec:
2
  serviceAccountName: workflow-sa

避免使用 root 用户：

1
templates:
2
- name: non-root
3
  container:
4
    image: busybox
5
    command: [sh, -c]
6
    args: ["whoami"]
7
  securityContext:
8
    runAsNonRoot: true
9
    runAsUser: 1000

使用 Secret 管理敏感信息：

1
templates:
2
- name: use-secret
3
  container:
4
    image: busybox
5
    command: [sh, -c]
6
    args: ["echo $PASSWORD"]
7
    env:
8
    - name: PASSWORD
9
      valueFrom:
10
        secretKeyRef:
11
          name: my-secret
12
          key: password

12.3 性能优化#

并行执行独立任务：

1
# 使用 DAG 而不是 Steps
2
templates:
3
- name: parallel-tasks
4
  dag:
5
    tasks:
6
    - name: task1
7
      template: worker
8
    - name: task2
9
      template: worker
10
    - name: task3
11
      template: worker

设置合理的超时时间：

1
spec:
2
  activeDeadlineSeconds: 3600  # 1 小时超时
3
  templates:
4
  - name: task-with-timeout
5
    activeDeadlineSeconds: 600  # 10 分钟超时
6
    container:
7
      image: busybox
8
      command: [sleep, "300"]

使用 PVC 复用：

1
spec:
2
  volumeClaimTemplates:
3
  - metadata:
4
      name: workdir
5
    spec:
6
      accessModes: [ "ReadWriteOnce" ]
7
      resources:
8
        requests:
9
          storage: 10Gi

12.4 可维护性#

使用 WorkflowTemplate 提高复用性：

1
# 定义通用模板
2
apiVersion: argoproj.io/v1alpha1
3
kind: WorkflowTemplate
4
metadata:
5
  name: common-tasks
6
spec:
7
  templates:
8
  - name: notify
9
    inputs:
10
      parameters:
11
      - name: message
12
    container:
13
      image: curlimages/curl
14
      command: [sh, -c]
15
      args:
16
      - |
17
        curl -X POST https://hooks.slack.com/services/xxx \
18
          -d '{"text":"{{inputs.parameters.message}}"}'

添加标签和注解：

1
metadata:
2
  generateName: my-workflow-
3
  labels:
4
    app: myapp
5
    env: production
6
    team: platform
7
  annotations:
8
    description: "Daily backup workflow"
9
    owner: "platform-team@example.com"

使用有意义的命名：

1
templates:
2
- name: checkout-source-code  # 清晰的名称
3
  container:
4
    image: alpine/git
5
    command: [git, clone, "{{workflow.parameters.repo}}"]

13. 总结#

Argo Workflows 是一个强大的 Kubernetes 原生工作流引擎，适用于 CI/CD、数据处理、机器学习等多种场景。

核心优势：

✅ 容器原生，与 Kubernetes 深度集成
✅ 支持复杂的 DAG 和并行执行
✅ 丰富的模板类型和可复用性
✅ 完善的可视化界面和 CLI 工具
✅ 活跃的社区和生态系统

适用场景：

CI/CD 流水线自动化
批量数据处理和 ETL
机器学习模型训练
基础设施自动化运维

学习路径：

掌握基本概念（Workflow、Template、Parameters）
实践简单案例（Hello World、Steps、DAG）
学习高级特性（工件传递、条件执行、重试）
构建实际项目（CI/CD 流水线、数据处理）
优化和监控（资源管理、性能优化、告警）

参考资源：

官方文档：https://argo-workflows.readthedocs.io
GitHub：https://github.com/argoproj/argo-workflows
示例仓库：https://github.com/argoproj/argo-workflows/tree/main/examples
社区论坛：https://argoproj.github.io/community/join-slack/

花日の博客

Argo Workflows 完全实战指南#

1. Argo Workflows 简介#

1.1 什么是 Argo Workflows#

1.2 核心特性#

1.3 应用场景#

1.4 Argo Workflows vs 其他工作流引擎#

2. 环境准备#

2.1 创建 Kind 集群#

3. 安装 Argo Workflows#

3.1 使用 Helm 安装#

3.2 验证安装#

3.4 配置工件仓库（可选）#

使用 MinIO（本地测试）#

使用阿里云 OSS#

4. 安装 Argo CLI#

macOS#

Linux#

5. 访问 Argo Server UI#

Port Forward（测试环境）#

6. 核心概念#

4.1 Workflow#

4.2 Template 类型#

模板定义类（Template Definitions）#

模板调用类（Template Invocators）#

4.3 参数（Parameters）#

4.4 工件（Artifacts）#

7. 实战案例#

7.1 案例 1：Hello World#

7.2 案例 2：Steps 顺序执行#

7.3 案例 3：DAG 并行执行#

7.4 案例 4：脚本执行#

7.5 案例 5：工件传递#

7.6 案例 6：条件执行#

7.7 案例 7：重试机制#

7.8 案例 8：CI/CD 流水线#

8. WorkflowTemplate 可复用模板#

8.1 创建 WorkflowTemplate#

8.2 使用 WorkflowTemplate#

9. CronWorkflow 定时任务#

9.1 创建 CronWorkflow#

9.2 管理 CronWorkflow#

10. 常用命令#

10.1 Workflow 管理#

10.2 使用 kubectl 管理#

11. 常见问题排查#

11.1 工作流一直处于 Pending 状态#

11.2 工作流执行失败#

11.3 工件传递失败#

11.4 权限问题#

12. 最佳实践#

12.1 资源管理#

12.2 安全最佳实践#

12.3 性能优化#

12.4 可维护性#

13. 总结#