Argo Workflows 常用命令（投递、跟踪与排障）

本文面向已在集群中安装 Argo Workflows 且配置好 `kubectl` 与 `argo` CLI 的场景，按「投递 → 观察 → 干预 → 排障 → 清理」组织命令。下文默认工作流类型为 `Workflow`（一次性运行）；模板与定时任务单独说明。
API 版本说明：工作流相关 Kubernetes 对象的 `apiVersion` 均为 `argoproj.io/v1alpha1`（与当前主流 Argo Workflows 发行版一致）。它表示 CRD 在 Kubernetes API 中的版本，不等于 Argo Controller / CLI 的 semver；后者请以 `argo version` 为准。本文中的 YAML 头、`kubectl` 资源类型均按 `argoproj.io/v1alpha1` 书写。
全局习惯：多数子命令支持 `-n <namespace>` / `--namespace` 指定命名空间；与 `kubectl` 当前上下文不一致时务必显式带上。

零、与 v1alpha1 对齐的清单（提交前自检）

投递用的 YAML 顶层应类似：

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  name: my-workflow-xxx
  namespace: my-ns
spec:
  entrypoint: main
  templates:
    - name: main
      container:
        image: alpine:3.20
        command: ["echo", "hello"]

同 API 版本下常用 kind 与 kubectl 资源名（kubectl api-resources --api-group=argoproj.io 中 VERSION 列为 v1alpha1）：

kind	常用 kubectl 全名
`Workflow`	`workflows.argoproj.io`（简写常为 `workflow` / `wf`，视集群别名而定）
`WorkflowTemplate`	`workflowtemplates.argoproj.io`
`CronWorkflow`	`cronworkflows.argoproj.io`
`ClusterWorkflowTemplate`	`clusterworkflowtemplates.argoproj.io`（集群级，无 namespace）

一、环境与前置检查

# CLI 与 Controller 是否匹配（semver；与 apiVersion v1alpha1 是两套概念）
argo version
# 当前能否列出工作流（命名空间按实际修改）
argo list -n default | head
# argoproj.io 下 v1alpha1 资源是否已注册
kubectl api-resources --api-group=argoproj.io | grep v1alpha1

若使用 远程 Argo Server（非 in-cluster 直连 Kubernetes API），需设置 ARGO_SERVER、ARGO_BASE_HREF 等，或使用：

1	argo <子命令> --server argo-server.argo:2746 --secure --token "$(cat token)"

具体以你方安装方式为准。

二、任务投递（Submit）

2.1 从 YAML 提交

# 基本提交
argo submit -n my-ns my-workflow.yaml
# 指定实例名（否则由集群生成）
argo submit -n my-ns my-workflow.yaml --name daily-qc-20260324
# 使用 generate-name 前缀（适合批量、避免重名）
argo submit -n my-ns my-workflow.yaml --generate-name qc-run-
# 干跑：只输出解析后的对象，不真正创建
argo submit -n my-ns my-workflow.yaml --dry-run -o yaml

常用参数：

参数	说明
`-f` / 文件路径	多个 `-f` 可合并多个 YAML（含 ConfigMap 式拆文件时）
`-p KEY=VALUE` / `--parameter`	覆盖工作流 `spec.arguments.parameters`
`--entrypoint`	覆盖 YAML 中的 `entrypoint`
`--serviceaccount`	运行工作流 Pod 使用的 SA
`--priority`	优先级（与集群是否启用 priority 相关）
`-l k=v`	给 Workflow 对象打 label，便于后续筛选
传参示例（对应模板里 `message` 参数）：

1	argo submit -n my-ns workflow.yaml -p message=hello -p threads=8

2.2 从集群内模板提交（WorkflowTemplate）

避免每次带大 YAML，只维护集群中的 WorkflowTemplate：

1
2
3

# 从 WorkflowTemplate 实例化（名称以你集群为准）
argo submit -n my-ns --from workflowtemplate/my-pipeline-template \
  -p sample-id=S001 -p ref=/refs/hg38.fa

--from 还可指向 ClusterWorkflowTemplate（API 同为 argoproj.io/v1alpha1，集群级资源），写法一般为：

1	argo submit -n my-ns --from clusterworkflowtemplate/my-global-template -p key=value

2.3 定时与批量习惯

CronWorkflow（apiVersion: argoproj.io/v1alpha1，kind: CronWorkflow）：用 argo cron create/update/list/get/delete 管理 CRON 定义；触发产生的是普通 Workflow（v1alpha1），后续仍用 list/get/logs 跟踪。
同一文件多次投递：配合 --generate-name 或每次 --name 唯一，避免 AlreadyExists。

三、任务跟踪（List / Get / Watch / UI）

3.1 列表与筛选

# 最近工作流（默认按时间排序，具体列因版本略有差异）
argo list -n my-ns
# 只关心未结束或失败
argo list -n my-ns --status Running
argo list -n my-ns --status Failed,Error
# 时间范围（适合日志/审计）
argo list -n my-ns --since 48h
# 按标签
argo list -n my-ns -l project=rnaseq

常用参数：--limit、--chunk-size（分页拉取大量历史时）、--no-headers（脚本解析）。

3.2 详情与节点 DAG

# 人类可读详情（各节点状态、消息）
argo get -n my-ns my-workflow-xxx
# 机器可读
argo get -n my-ns my-workflow-xxx -o yaml
argo get -n my-ns my-workflow-xxx -o json

节点处于 Pending / Running / Succeeded / Failed / Error / Skipped 等状态时，argo get 是最快的「一张表看清 DAG」方式。

3.3 实时观察

1 2	# 阻塞直到工作流结束（适合 CI 或终端盯着跑） argo watch -n my-ns my-workflow-xxx

3.4 日志

# 拉取与工作流关联的 Pod 日志（多 Pod 时会聚合或需指定）
argo logs -n my-ns my-workflow-xxx
# 持续跟随
argo logs -n my-ns my-workflow-xxx -f
# 指定步骤名（与模板中节点名一致）
argo logs -n my-ns my-workflow-xxx step-align
# 多容器 Pod 指定容器
argo logs -n my-ns my-workflow-xxx -c main
# 只看最后 N 行
argo logs -n my-ns my-workflow-xxx --tail 200

若 argo logs 因权限或已完成 Pod 被回收而不可用，可直接用 kubectl logs 查工作流 Pod（见下一节）。

3.5 Web UI（可选）

常见做法是对 argo-server Service 做 port-forward，在浏览器里看 DAG 与日志；CLI 与 UI 看到的是同一套 CRD 数据。

1 2	kubectl -n argo port-forward svc/argo-server 2746:2746 # 浏览器打开 https://localhost:2746 （是否 https、路径前缀依安装而定）

四、运行中干预（Suspend / Resume / Stop / Terminate）

4.1 暂停与继续

适用于模板里有 suspend、或你希望先停住队列再放开的情况：

1 2	argo suspend -n my-ns my-workflow-xxx argo resume -n my-ns my-workflow-xxx

4.2 停止与终止

# 优雅停止（可选策略，视版本文档）
argo stop -n my-ns my-workflow-xxx
# 强制终止（尽快结束，失败/中断语义）
argo terminate -n my-ns my-workflow-xxx

实际语义以当前 Controller semver 为准：`stop` 与 `terminate` 在「是否允许 onExit」「子 Pod 如何收尾」上可能有差异；排障时以 `argo get` 与 `Workflow.status`（v1alpha1 对象状态）为准。

五、失败与重试（Retry / Resubmit）

5.1 对失败工作流重试

在 不重新手写 YAML 的前提下，让控制器按策略重跑失败节点：

1	argo retry -n my-ns my-workflow-xxx

部分场景可结合 CLI 提供的选项（以 argo retry --help 为准），例如：

仅重试特定条件失败的节点（字段选择器等，视 CLI 而定）
--restart-successful：连已成功节点也重跑（慎用，适合「输出不可信需整体重算」）

5.2 整体再跑一遍（新实例）

保留旧实例审计，同时起一个新 Workflow：

1	argo resubmit -n my-ns my-workflow-xxx

可与 `-p` 覆盖参数（是否支持在 `resubmit` 上传参以 `argo resubmit --help` 为准）；不支持则先 `argo get -n my-ns my-workflow-xxx -o yaml` 得到 v1alpha1 清单，编辑后 `kubectl apply` 或 `argo submit`。

六、失败核查（排障清单）

按「从外到内」顺序执行，一般能快速定位。

6.1 工作流级：消息与事件

argo get -n my-ns my-workflow-xxx
# 显式使用 v1alpha1 资源类型（与简写 workflow 等价时二选一即可）
kubectl describe workflows.argoproj.io my-workflow-xxx -n my-ns
kubectl get events -n my-ns --field-selector involvedObject.name=my-workflow-xxx --sort-by='.lastTimestamp'

关注：message、conditions、是否 OOM、ImagePullBackOff、quota、RBAC 拒绝。

6.2 Pod 级：状态与日志

# 列出该工作流产生的 Pod（label 以你集群为准，常见如下）
kubectl get pods -n my-ns -l workflows.argoproj.io/workflow=my-workflow-xxx
kubectl describe pod -n my-ns <pod-name>
kubectl logs -n my-ns <pod-name> -c main --tail=500
kubectl logs -n my-ns <pod-name> -c init --tail=200   # init 容器失败时必看

Sidecar、wait 容器名因版本而异，kubectl describe pod 里会列出所有 container。

6.3 配置与 YAML 校验

1 2	# 提交前静态检查 argo lint my-workflow.yaml

可减少「模板引用错误、变量未替换、DAG 依赖不存在」等一类低级错误。

6.4 已完成工作流被 TTL / GC 删掉

若开启了 `ttlStrategy` 或工作流归档，集群里可能只剩归档库或对象存储中的记录；需查你方 workflow archive 或审计日志。日常排障建议适当增大 TTL 或在失败时先 `argo get -o yaml > backup.yaml` 留档。

七、模板与定时任务（简要）

# WorkflowTemplate
argo template list -n my-ns
argo template get -n my-ns my-pipeline-template -o yaml
# CronWorkflow
argo cron list -n my-ns
argo cron get -n my-ns nightly-backup
argo cron suspend -n my-ns nightly-backup
argo cron resume -n my-ns nightly-backup

八、清理与下线（Delete）

# 删除单个工作流（通常会级联清理其管理的资源，行为与 finalizer 相关）
argo delete -n my-ns my-workflow-xxx
# 批量：先 list 再 delete，或用 label selector（以 argo delete --help 为准）
argo delete -n my-ns -l project=temp-run

生产环境删除前确认无下游依赖该 Workflow 名称或 label。

九、与 kubectl 的对照关系（心智模型，v1alpha1）

YAML 中须含 apiVersion: argoproj.io/v1alpha1 与对应 kind。

意图	Argo CLI	kubectl（等价思路，资源名显式到 API 组）
提交	`argo submit`	`kubectl create -f workflow.yaml`（文件内为 `Workflow` / v1alpha1）
列表	`argo list`	`kubectl get workflows.argoproj.io -n <ns>`
详情	`argo get`	`kubectl get workflows.argoproj.io <name> -n <ns> -o yaml` + `describe`
模板	`argo template …`	`kubectl get workflowtemplates.argoproj.io -n <ns>`
定时	`argo cron …`	`kubectl get cronworkflows.argoproj.io -n <ns>`
日志	`argo logs`	`kubectl logs` 指向具体 Pod
删除	`argo delete`	`kubectl delete workflows.argoproj.io <name> -n <ns>`
日常开发可优先 Argo CLI；与平台同学联调或排查 CNI、存储、SA 时，kubectl describe/get events 往往不可替代。

十、速查：最常用命令组合

# 1. 提交并立刻跟跑（先起唯一名，避免猜实例名）
RUN=job-$(date +%Y%m%d%H%M%S)
argo submit -n my-ns wf.yaml --name "$RUN"
argo watch -n my-ns "$RUN"
# 2. 找最近失败
argo list -n my-ns --status Failed --limit 20
# 3. 看失败原因 + 日志
WF=my-workflow-xxx
argo get -n my-ns "$WF"
argo logs -n my-ns "$WF" --tail 300
# 4. 修数据/代码后重试
argo retry -n my-ns "$WF"

若使用 `--generate-name`，可从 `argo submit` 的标准输出里复制返回的 Workflow 名称，再执行 `argo watch -n my-ns <该名称>`；部分版本支持 `argo submit ... -o name` 仅输出资源名，便于脚本拼接。

小结：资源定义与 kubectl 侧类型以 argoproj.io/v1alpha1 为准；CLI 子命令、flag、label 键名仍可能随 Argo Workflows 发行版（semver） 微调。遇 flag 报错时用 argo <子命令> --help 核对本机 CLI；对象字段语义以集群内已安装的 Workflow CRD 为准，例如：

1
2
3

kubectl explain workflows.argoproj.io.spec
# 若需显式指定 API 版本（视 kubectl 版本而定）：
kubectl explain workflows.argoproj.io.spec --api-version=argoproj.io/v1alpha1