Argo Workflows 操作 Pod（启动、进入、暂停、关闭与日志）

在 Argo Workflows 中，每个任务步骤通常对应一个 Pod（容器组，Pod）。工作流控制器负责创建与回收 Pod；日常排障与干预则主要依赖 kubectl，必要时配合 argo 在工作流层面暂停或终止。下文默认命名空间为 my-ns，Pod 名为 <pod-name>，工作流实例名为 my-workflow-xxx；与当前 kubectl 上下文不一致时，请始终显式加上 -n my-ns。

段末注释：Pod 是 Kubernetes 中最小的调度单元，内含一个或多个容器；Argo 任务 Pod 常见 init、wait、main 等容器名。

零、Pod 操作命令速查（先看这里）

以下命令按「定位 → 启动 → 观察 → 进入 → 暂停 → 关闭 → 日志」排列，可直接复制后替换占位符使用。

# ── 1. 定位：找到某个工作流产生的 Pod ──
kubectl get pods -n my-ns -l workflows.argoproj.io/workflow=my-workflow-xxx
kubectl get pod -n my-ns <pod-name> -o wide

# ── 2. 启动：由工作流自动创建（常规路径）──
argo submit -n my-ns my-workflow.yaml --name my-workflow-xxx
# 或手动起一个调试 Pod（不经过 Argo 模板）
kubectl run -n my-ns debug-shell --image=alpine:3.20 --restart=Never -- sleep 3600

# ── 3. 观察：状态、事件、资源 ──
kubectl describe pod -n my-ns <pod-name>
kubectl get events -n my-ns --field-selector involvedObject.name=<pod-name> --sort-by='.lastTimestamp'

# ── 4. 进入：交互式 Shell ──
kubectl exec -n my-ns -it <pod-name> -c main -- /bin/sh
# 无 sh 时试 bash；多容器 Pod 必须 -c 指定容器

# ── 5. 暂停：工作流 / 模板级（单 Pod 无原生「冻结」）──
argo suspend -n my-ns my-workflow-xxx          # 暂停整个工作流
argo resume -n my-ns my-workflow-xxx             # 继续

# ── 6. 关闭：删 Pod 或停工作流 ──
kubectl delete pod -n my-ns <pod-name>           # 删除单个 Pod
argo stop -n my-ns my-workflow-xxx               # 优雅停止工作流
argo terminate -n my-ns my-workflow-xxx          # 强制终止工作流

# ── 7. 日志 ──
kubectl logs -n my-ns <pod-name> -c main --tail=200 -f
argo logs -n my-ns my-workflow-xxx --tail=200 -f
kubectl logs -n my-ns <pod-name> -c main --previous   # 容器重启前一轮日志

全局习惯：几乎所有 kubectl 子命令支持 -n <namespace>；脚本中建议 --request-timeout=30s 避免 API 卡住。

一、先找到要操作的 Pod

Argo 为每个工作流步骤创建的 Pod 通常带有固定标签，用标签筛选比凭名字猜测更可靠。

1.1 按工作流名列出 Pod

1	kubectl get pods -n my-ns -l workflows.argoproj.io/workflow=my-workflow-xxx

常见补充标签（视集群 Argo 版本与配置而定）：

标签键	含义
`workflows.argoproj.io/workflow`	所属 Workflow 实例名
`workflows.argoproj.io/template`	对应模板名（步骤名）
`workflows.argoproj.io/completed`	是否已完成（部分版本）

1.2 从 `argo get` 反查 Pod 名

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

输出中的 NODE ID / POD NAME 列即各步骤 Pod；失败节点优先看 Failed / Error 对应行。

1.3 常用查看参数

# 宽表：节点、状态、重启次数、运行时长
kubectl get pods -n my-ns -l workflows.argoproj.io/workflow=my-workflow-xxx -o wide

# 仅输出 Pod 名（脚本友好）
kubectl get pods -n my-ns -l workflows.argoproj.io/workflow=my-workflow-xxx -o name

# YAML/JSON 机器可读（查 container 名、volume、状态细节）
kubectl get pod -n my-ns <pod-name> -o yaml

应用场景：提交工作流后第一步永远是「列出 Pod → 确认 Pending/Running 是否正常」；多并行步骤时标签筛选可避免看错 Pod。

二、启动 Pod

需区分两种语义：（A）让 Argo 为工作流创建任务 Pod；（B）在集群里手动起一个独立 Pod（调试镜像、网络、存储）。

2.1 路径 A：通过工作流启动（常规生产路径）

工作流被提交后，控制器按 DAG/steps 自动创建 Pod，无需手动 kubectl run。

# 提交并指定实例名，便于后续查 Pod
argo submit -n my-ns my-workflow.yaml --name my-workflow-xxx

# 提交后立刻列出 Pod（可能尚未全部创建）
kubectl get pods -n my-ns -l workflows.argoproj.io/workflow=my-workflow-xxx -w

参数 / 行为	说明
`argo submit -n <ns> <file>`	创建 `Workflow` CR，控制器开始调度 Pod
`--name`	固定 Workflow 名，对应 label `workflows.argoproj.io/workflow`
`--generate-name prefix-`	批量投递，每次生成唯一 Workflow 名
`-p KEY=VALUE`	传参，影响模板渲染与镜像/命令
`kubectl get pods … -w`	持续 watch Pod 状态直到 Running/Succeeded

Pod 长时间 Pending 时，用 kubectl describe pod 看 Events（资源不足、亲和性、PVC 未绑定、镜像拉取等），而非重复 submit。

2.2 路径 B：手动启动调试 Pod

用于验证 SA、PVC、镜像拉取、DNS，与 Argo 解耦：

# 一次性 Pod（restartPolicy 隐含为 Never）
kubectl run -n my-ns debug-shell \
  --image=alpine:3.20 \
  --restart=Never \
  --overrides='{"spec":{"containers":[{"name":"debug-shell","image":"alpine:3.20","command":["sleep","3600"]}]}}' \
  -- sleep 3600

# 从 YAML 启动（可挂载 PVC、指定 SA，与工作流 Pod 配置对齐）
kubectl apply -n my-ns -f debug-pod.yaml

debug-pod.yaml 最小示例：

apiVersion: v1
kind: Pod
metadata:
  name: debug-pod
  namespace: my-ns
spec:
  restartPolicy: Never
  serviceAccountName: my-workflow-sa
  containers:
    - name: main
      image: your-registry/your-image:tag
      command: ["sleep", "infinity"]
      resources:
        requests:
          cpu: "500m"
          memory: "1Gi"

字段	说明
`restartPolicy: Never`	与 Argo 任务 Pod 一致，退出后不自动重启
`serviceAccountName`	与工作流相同 SA，复现 RBAC 问题
`command`	调试时常用 `sleep infinity` 保持 Pod 存活

2.3 「重启」失败步骤 Pod 的说明

Argo 不会因为你删除某个步骤 Pod 就自动在同一 Workflow 实例里重跑该步骤（除非使用 argo retry 等工作流级操作）。删除运行中 Pod 可能导致工作流标记失败。生产上应用：

1 2	argo retry -n my-ns my-workflow-xxx # 按策略重试失败节点 argo resubmit -n my-ns my-workflow-xxx # 新建 Workflow 实例整体再跑

应用场景：镜像或数据修复后重跑失败节点用 retry；需要保留旧实例审计、起新跑批用 resubmit。

三、进入 Pod（exec）

在 Pod 内执行交互式 Shell 或单次命令，是排障、手动验数据的最直接手段。

3.1 交互式进入

1 2	kubectl exec -n my-ns -it <pod-name> -c main -- /bin/sh kubectl exec -n my-ns -it <pod-name> -c main -- /bin/bash

参数	说明
`-n`	命名空间
`-i`	保持 STDIN 打开（交互）
`-t`	分配 TTY（终端）
`-c main`	容器名；Argo 主业务容器多为 `main`，init/wait 容器无法 exec 长期 Shell
`--` 之后	要在容器内执行的命令

3.2 非交互：执行单条命令

1
2
3

kubectl exec -n my-ns <pod-name> -c main -- ls -la /tmp
kubectl exec -n my-ns <pod-name> -c main -- env | grep ARGO
kubectl exec -n my-ns <pod-name> -c main -- cat /var/run/argo/outputs/parameters/result

适合脚本化检查：磁盘、环境变量、Argo 输出路径等。

3.3 多容器 Pod

# 先看容器列表
kubectl get pod -n my-ns <pod-name> -o jsonpath='{.spec.containers[*].name}{"\n"}'

# 分别进入
kubectl exec -n my-ns -it <pod-name> -c wait -- /bin/sh
kubectl exec -n my-ns -it <pod-name> -c main -- /bin/sh

Argo 常见容器角色：

容器	典型作用
`init` / `init` 系列	拉取 artifact、准备目录
`wait`	等待主容器、上报状态
`main`	用户任务（优先 exec 这里）

3.4 常见问题

现象	处理
`executable file not found`	镜像无 `/bin/sh`，换 `bash` 或直接 exec 二进制
`container not found`	用 `describe pod` 确认容器名
Pod 已 `Completed`	若未开启立即 GC，仍可 exec；若 Pod 已删，需 `retry`/`resubmit` 或手动 debug Pod
权限不足	检查 RBAC 是否允许 `pods/exec`

应用场景：任务报「文件不存在」时进 Pod 查路径；生物信息学任务中检查 reference、中间 BAM/FASTQ 是否挂载正确。

四、暂停 Pod / 工作流

Kubernetes 没有「暂停单个 Running Pod 内进程但保留 Pod 对象」的一等公民 API。在 Argo 场景下，「暂停」通常指下面几层语义。

4.1 暂停整个工作流（最常用）

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

命令	效果
`argo suspend`	工作流进入 Suspended；尚未启动的后续节点不再调度；已 Running 的 Pod 一般继续跑完当前步骤（视 Controller 版本与配置）
`argo resume`	从暂停点继续调度

适用：发现上游数据有问题，先停住队列，修正后再放开。

4.2 模板内 `suspend` 步骤（计划内暂停）

在工作流 YAML 中插入 suspend 模板，可无限期等待人工 argo resume，或 duration: "30m" 定时自动继续：

1 2	- name: wait-for-qc suspend: {}

这是设计上的检查点，不是对已运行 Pod 的 cgroup 冻结。

4.3 与「单 Pod 暂停」相关的边界说明

期望	可行做法
不让新任务再起 Pod	`argo suspend` 或删除/暂停 CronWorkflow
立刻停止某个 Running Pod	`kubectl delete pod` 或 `argo terminate`（见第五节）
冻结 Pod 内 CPU/内存	集群级高级能力（如 cgroup v2 freeze），非 kubectl 常规操作，Argo 文档一般不涉及

应用场景：批跑中发现样本清单错误 → argo suspend；审批通过 → argo resume。不要误以为 kubectl pause 存在（Deployment 有 scale，Pod 无 pause 子命令）。

五、关闭 / 停止 Pod

5.1 删除单个 Pod

1	kubectl delete pod -n my-ns <pod-name>

参数	说明
`--grace-period=30`	优雅退出宽限秒数（默认 30）
`--force`	与 `--grace-period=0` 联用，强制删除（慎用，可能导致数据未刷盘）
`--wait=false`	不阻塞等待删除完成

对 Argo 管理的运行中步骤 Pod，删除可能导致该节点失败并触发工作流失败策略；仅在明确要中断该步骤时使用。

5.2 停止 / 终止整个工作流

1 2	argo stop -n my-ns my-workflow-xxx argo terminate -n my-ns my-workflow-xxx

命令	语义（概览）
`argo stop`	请求优雅结束；是否执行 `onExit`、如何收尾子 Pod 视版本与 Workflow 配置而定
`argo terminate`	更激进地结束工作流，尽快杀掉相关 Pod

精确语义以本机 argo stop --help 与集群 Controller 版本为准；操作后用 argo get 确认状态。

5.3 清理已完成 Pod（GC 策略）

工作流 YAML 中 podGC 控制 Pod 何时被控制器删除，例如：

1
2
3

podGC:
  strategy: OnWorkflowCompletion   # 工作流结束后删 Pod
  # 或 OnPodCompletion、OnPodSuccess 等

手动清理某工作流残留 Pod：

1	kubectl delete pods -n my-ns -l workflows.argoproj.io/workflow=my-workflow-xxx

应用场景：调试完毕删手动 kubectl run 的 Pod；生产失败实例占磁盘时用 label 批量 delete；整单作废用 terminate。

六、查看 Pod 日志

6.1 kubectl logs（Pod 级，最细粒度）

# 主容器最近 200 行并持续跟随
kubectl logs -n my-ns <pod-name> -c main --tail=200 -f

# 带时间戳
kubectl logs -n my-ns <pod-name> -c main --timestamps

# 仅最近 1 小时（需集群日志后端支持时更有效；否则配合 --since）
kubectl logs -n my-ns <pod-name> -c main --since=1h

# 限制字节/行数（防刷屏）
kubectl logs -n my-ns <pod-name> -c main --limit-bytes=1048576

参数	说明
`-c <container>`	指定容器；省略时若仅一个容器则可省略
`-f` / `--follow`	持续输出新日志
`--tail N`	只显示最后 N 行
`--since`	相对时间，如 `10m`、`1h`
`--previous`	上一次崩溃/重启前的容器日志，OOM/CrashLoop 必看
`--timestamps`	每行前加时间戳

Init 容器失败（Pod 未进入 Running）：

1	kubectl logs -n my-ns <pod-name> -c init --tail=300

6.2 argo logs（工作流级聚合）

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 --tail=200
argo logs -n my-ns my-workflow-xxx -c main

参数	说明
步骤名（位置参数）	与模板节点名一致，只拉该步骤
`-c`	多容器时指定容器
`-f`	follow
`--tail`	尾部行数

当 Pod 已被 podGC 删除或无权 list Pod 时，argo logs 可能不可用，需依赖集群日志栈（Loki/ELK）或事先 --tail 落盘。

6.3 多 Pod / 并行步骤

# 同一 Workflow 下所有 Pod 逐个看
for p in $(kubectl get pods -n my-ns -l workflows.argoproj.io/workflow=my-workflow-xxx -o name); do
  echo "===== $p ====="
  kubectl logs -n my-ns "${p#pod/}" -c main --tail=50
done

可选工具 stern（需单独安装）：按 label 同时 follow 多个 Pod 日志。

应用场景：CrashLoopBackOff 先 --previous；artifact 下载失败看 init；DAG 中定位失败步骤用 argo logs <step-name>。

七、状态观察与排障（配合日志）

# 人类可读：Events、Conditions、容器状态
kubectl describe pod -n my-ns <pod-name>

# 事件时间线
kubectl get events -n my-ns --field-selector involvedObject.name=<pod-name> --sort-by='.lastTimestamp'

# 资源占用（需 metrics-server）
kubectl top pod -n my-ns <pod-name>

describe 中重点字段：

字段	含义
`State: Waiting` + `Reason`	如 `ImagePullBackOff`、`ContainerCreating`
`Last State: Terminated` + `Reason: OOMKilled`	内存超限
`Events`	调度失败、挂载失败、探针失败等

八、Argo Pod 与 kubectl 对照（心智模型）

意图	推荐命令	说明
列出工作流 Pod	`kubectl get pods -l workflows.argoproj.io/workflow=…`	精确到 Pod
启动任务 Pod	`argo submit`	由控制器创建
临时调试 Pod	`kubectl run` / `apply`	非 Argo 管理
进入容器	`kubectl exec -it … -c main`	指定主容器
暂停调度	`argo suspend` / `resume`	工作流级
停止运行	`argo stop` / `terminate`	工作流级
删单个 Pod	`kubectl delete pod`	谨慎用于 Running 步骤
看日志	`kubectl logs` / `argo logs`	Pod 级 / 步骤级

日常原则：跟踪 DAG 用 argo get；查镜像、挂载、Events 用 kubectl describe pod；看业务输出用 kubectl logs -c main。

九、典型排障组合（复制即用）

WF=my-workflow-xxx
NS=my-ns

# 1. 工作流 → Pod 列表
argo get -n "$NS" "$WF"
kubectl get pods -n "$NS" -l workflows.argoproj.io/workflow="$WF" -o wide

# 2. 假设失败 Pod 名已得知
POD=<pod-name>
kubectl describe pod -n "$NS" "$POD"
kubectl logs -n "$NS" "$POD" -c init --tail=100
kubectl logs -n "$NS" "$POD" -c main --tail=300
kubectl logs -n "$NS" "$POD" -c main --previous

# 3. 需要进 Pod 看文件
kubectl exec -n "$NS" -it "$POD" -c main -- /bin/sh

# 4. 修正后重试
argo retry -n "$NS" "$WF"

小结：Argo 任务 Pod 的生命周期由 Workflow 控制器驱动；kubectl 负责 Pod 级的 exec、logs、describe、delete，argo 负责 submit、suspend/resume、stop/terminate、retry 等工作流级语义。单 Pod 「暂停」在 Kubernetes 中并非标准操作，应通过 工作流 suspend 或 终止/删除 表达意图。命令 flag 以本机 kubectl version、argo version 为准；遇 RBAC 拒绝时，让集群管理员确认对 pods、pods/log、pods/exec 的权限。