Argo Workflows 环境变量配置完全指南:Controller、Executor 与 Argo Server 全量参数详解

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

Argo Workflows 环境变量配置完全指南:Controller、Executor 与 Argo Server 全量参数详解

环境变量是 Argo Workflows 在部署与运行阶段调整组件行为的重要入口:从 Controller 的调度节流、垃圾回收周期、大工作流节点状态压缩,到 Executor 的资源状态轮询间隔、S3 上传并发度,再到 Argo Server 的 gRPC 消息上限与限流头配置,均可通过环境变量完成。本文以 docs/environment-variables.md 为骨架,结合仓库源码(util/env/env.go、workflow/controller/controller.go、util/retry/retry.go 等)逐项解读三大组件的全部环境变量,并给出 Deployment 与 ConfigMap 中的标准注入方式,帮助你精准调优自建 Argo Workflows 集群。

环境变量使用须知:实验特性,随时可能变更

在动手配置前,请先记住原文档给出的重要警告:

环境变量通常用于测试实验性特性,绝大多数用户不应该使用它们;这些环境变量随时可能被移除。

这意味着环境变量不应被视为长期稳定的公开 API。与 workflow-controller-configmap(参见 workflow-controller-configmap.md)中结构化的 YAML 配置相比,环境变量更适合做一次性调优、故障排查或新版本特性验证。配置时建议记录使用的变量与值,并关注上游 CHANGELOG(CHANGELOG.md)中的变更说明。

从源码结构看,Controller 侧的多数变量通过 util/env/env.go 提供的辅助函数读取:

// util/env/env.go
func LookupEnvDurationOr(ctx context.Context, key string, o time.Duration) time.Duration {
	v, found := os.LookupEnv(key)
	if found && v != "" {
		d, err := time.ParseDuration(v)
		if err == nil {
			return d
		}
		// 解析失败会 panic 并记录日志
	}
	return o // 未设置或解析失败时回退到默认值
}

同文件还提供 LookupEnvIntOr、LookupEnvFloatOr、LookupEnvStringOr,分别用于 int、float、string 类型变量。由此可以推断:只要设置了非空值,变量的类型解析就会严格进行,格式非法(如把 time.Duration 写成 30 而非 30s)会导致组件启动失败,因此填写值时必须带上完整单位(如 5m、1h、30s)。

Controller 环境变量全表与分组解读

Controller(workflow-controller)是工作流调度的核心组件,下表完整列出其全部环境变量。

全量参数表

Name Type Default Description
ARGO_AGENT_TASK_WORKERS int 16 agent pod 的任务 worker 数量。
ALL_POD_CHANGES_SIGNIFICANT bool false Pod 协调(reconciliation)时是否把所有 pod 变更都视为"重要变更"。
ALWAYS_OFFLOAD_NODE_STATUS bool false 是否总是卸载(offload)节点状态。
ARCHIVED_WORKFLOW_GC_PERIOD time.Duration 24h 已归档工作流(archived workflows)的 GC 周期。
ARGO_PPROF bool false 启用 pprof 性能剖析端点。
ARGO_PROGRESS_PATCH_TICK_DURATION time.Duration 1m 自我上报的进度(progress)被打补丁写入 pod 注解的频率,即 Controller 感知进度变化所需的时间;设为 0 可禁用进度自我上报。
ARGO_PROGRESS_FILE_TICK_DURATION time.Duration 3s Executor 读取进度文件的频率;设为 0 可禁用进度自我上报。
ARGO_REMOVE_PVC_PROTECTION_FINALIZER bool true 在标记工作流创建的 PVC 为待删除后,移除其上的 kubernetes.io/pvc-protection finalizer,避免删除被阻塞直至 pod 被删除。
ARGO_TRACE string `` 是否在 Argo 组件中启用追踪(tracing)语句。
ARGO_ARTIFACT_GC_RETRY_WINDOW time.Duration 60m 工作流完成(或被删除)后,Controller 持续重试失败的人工制品 GC 启动的时间窗口,超过后放弃。
ARGO_AGENT_PATCH_RATE time.Duration DEFAULT_REQUEUE_TIME Argo Agent 对工作流 task-set 打补丁的速率。
ARGO_AGENT_CPU_LIMIT resource.Quantity 100m Agent 的 CPU 资源上限。
ARGO_AGENT_MEMORY_LIMIT resource.Quantity 256m Agent 的内存资源上限。
ARGO_POD_STATUS_CAPTURE_FINALIZER bool false finalizer 会阻塞 pod 删除,直到 Controller 捕获其状态。
BUBBLE_ENTRY_TEMPLATE_ERR bool true 是否把模板错误上抛(bubble up)到工作流。
CACHE_GC_PERIOD time.Duration 0s 记忆化(memoization)缓存 GC 的频率;默认禁用,设置非零值即可启用。
CACHE_GC_AFTER_NOT_HIT_DURATION time.Duration 30s 记忆化缓存在此时间段内未被命中时将被删除。
CRON_SYNC_PERIOD time.Duration 10s Cron 工作流的同步频率。
DEFAULT_REQUEUE_TIME time.Duration 10s 工作流队列限流器的重新入队时间。
DISABLE_MAX_RECURSION bool false 设为 true 可禁用递归防护器;该防护器会阻止调用子模板已达 100 次的工作流继续运行。
EXPRESSION_TEMPLATES bool true 禁用表达式模板的逃生舱口(escape hatch)。
EVENT_AGGREGATION_WITH_ANNOTATIONS bool false 聚合事件时是否使用事件注解。
GZIP_IMPLEMENTATION string PGZip 压缩/解压实现,目前仅支持 PGZip 与 GZip。
HEALTHZ_AGE time.Duration 5m 未协调的工作流达到该年龄时被报告为不健康。
INDEX_WORKFLOW_SEMAPHORE_KEYS bool true 是否为信号量(semaphore)建立索引。
LEADER_ELECTION_IDENTITY string Controller 的 metadata.name 工作流 Controller 选举 leader 使用的 ID。
LEADER_ELECTION_DISABLE bool false 是否禁用 leader 选举;设为 true 时,还应将 Deployment 的滚动更新策略改为 Recreate,防止滚动更新期间两个 Controller 并发运行(详见 high-availability.md)。
LEADER_ELECTION_LEASE_DURATION time.Duration 15s 非 leader 候选者等待强制获取领导权的时间。
LEADER_ELECTION_RENEW_DEADLINE time.Duration 10s 现任 master 放弃前重试刷新领导权的持续时间。
LEADER_ELECTION_RETRY_PERIOD time.Duration 5s leader 选举客户端两次动作之间等待的时间。
MAX_OPERATION_TIME time.Duration 30s 单个工作流操作允许运行的最长时间,超时后工作流会被重新放入工作队列。
OFFLOAD_NODE_STATUS_TTL time.Duration 5m 删除已卸载节点状态的 TTL;目前仅用于测试。
OPERATION_DURATION_METRIC_BUCKET_COUNT int 6 操作耗时指标收集的桶(bucket)数量。
POD_NAMES string v2 pod 名是包含模板名(v2)还是节点 id(v1);Argo Server 应设置相同的值。
PROMETHEUS_LEGACY_NAME_VALIDATION_SCHEME bool false 通过将 NameValidationScheme 设为 LegacyValidation,让 Prometheus 仅以下划线作为分隔符发出指标。
RECENTLY_STARTED_POD_DURATION time.Duration 10s pod 在多久时间内被视为"刚启动"。
RECENTLY_DELETED_POD_DURATION time.Duration 2m pod 在多久时间内被视为"刚删除"。
TASK_RESULT_TIMEOUT_DURATION time.Duration 10m 节点已标记完成但 taskresult 尚未到达的超时时间;它是比 RECENTLY_DELETED_POD_DURATION 更通用、更保守的版本,用于 taskresult 未到但 pod 仍存在的情况。
RETRY_BACKOFF_DURATION time.Duration 10ms 重试 API 调用时的退避时长。
RETRY_BACKOFF_FACTOR float 2.0 重试 API 调用时的退避因子。
RETRY_BACKOFF_STEPS int 5 重试 API 调用时的退避步数。
RETRY_HOST_NAME_LABEL_KEY string kubernetes.io/hostname 重试模板时使用的主机名标签键。
TRANSIENT_ERROR_PATTERN string "" 表示额外瞬态错误模式的正则表达式。
WORKFLOW_COMPRESSION_ALGORITHM string gzip 大工作流节点状态的压缩算法:gzip、zstd 或 brotli。解压会自动检测算法,但使用非 gzip 算法写入的工作流无法被不支持该算法的旧版本读取,因此只有在所有组件都升级后才应更改(详见 offloading-large-workflows.md)。
WORKFLOW_COMPRESSION_LEVEL int 随算法而异 WORKFLOW_COMPRESSION_ALGORITHM 的压缩级别。范围与默认值取决于算法:gzip 1-9(默认 6)、zstd 1-4(默认 2)、brotli 0-11(默认 6)。大小/速度权衡详见 offloading-large-workflows.md。
WF_DEL_PROPAGATION_POLICY string "" 工作流的删除传播策略。
WORKFLOW_GC_PERIOD time.Duration 5m 工作流 GC 的周期。
SEMAPHORE_NOTIFY_DELAY time.Duration 1s 信号量可用时通知等待者的调优延迟。
WATCH_CONTROLLER_SEMAPHORE_CONFIGMAPS bool true 是否监听 Controller 的 ConfigMap 与信号量 ConfigMap 以获取运行时变更;禁用后 Controller 只会读取一次,需手动重启才能感知新变更。
SKIP_WORKFLOW_DURATION_ESTIMATION bool false 是否跳过从历史工作流查询资源用量来估算新工作流时长的逻辑。
WORKFLOW_ESTIMATION_DB_QUERY_TIMEOUT_SECONDS int 5 估算工作流时长时的数据库查询超时(秒);防止数据库慢或锁定时阻塞工作流执行。
WORKFLOW_USER_OVERRIDE_ALLOWLIST string "" 逗号分隔的 WorkflowSpec 字段名(YAML/JSON 名,如 podSpecPatch,volumes)白名单,允许 workflowTemplateRef 提交者在 templateReferencing: Strict/Secure 下设置的字段。非法名称会导致 Controller 启动失败;嵌套的 artifactGC 安全字段不会被放宽。

分组解读:这些变量在源码中如何生效

调度与队列调优。DEFAULT_REQUEUE_TIME(默认 10s)是工作流队列限流器的重入队间隔,在 workflow/controller/controller.go 中通过 env.LookupEnvDurationOr(ctx, common.EnvVarDefaultRequeueTime, 10*time.Second) 读取,常量定义见 workflow/common/common.go。MAX_OPERATION_TIME(默认 30s)限制单次操作时长,超时后工作流被重新入队,是防止单个工作流卡死队列的关键参数。ARGO_AGENT_TASK_WORKERS 控制 agent pod 的任务 worker 数,与 ARGO_AGENT_PATCH_RATE(默认跟随 DEFAULT_REQUEUE_TIME)共同决定任务集的吞吐。

Agent 资源限制。ARGO_AGENT_CPU_LIMIT 与 ARGO_AGENT_MEMORY_LIMIT 在 workflow/controller/agent.go 中解析为 agent pod 的资源限额:

Limits: map[apiv1.ResourceName]resource.Quantity{
    "cpu":    resource.MustParse(env.LookupEnvStringOr("ARGO_AGENT_CPU_LIMIT", "100m")),
    "memory": resource.MustParse(env.LookupEnvStringOr("ARGO_AGENT_MEMORY_LIMIT", "256M")),
},

Pod 协调灵敏度。ALL_POD_CHANGES_SIGNIFICANT 控制 pod 协调时何种变更才算"重要"。在 workflow/controller/pod/significant.go 中:

func significantPodChange(from *apiv1.Pod, to *apiv1.Pod) bool {
	return os.Getenv("ALL_POD_CHANGES_SIGNIFICANT") == "true" ||
		from.Spec.NodeName != to.Spec.NodeName ||
		from.Status.Phase != to.Status.Phase ||
		from.Status.Message != to.Status.Message ||
		// ...
}

其测试用例 workflow/controller/pod/significant_test.go 验证了设置为 true 后任意 pod 变更都会被判定为重要变更。

垃圾回收节奏。WORKFLOW_GC_PERIOD(默认 5m)与 ARCHIVED_WORKFLOW_GC_PERIOD(默认 24h)分别在 workflow/controller/controller.go 与 workflow/controller/controller.go 中被读取,分别驱动工作流 GC 协程与归档工作流 GC 协程;后者的实际生效还依赖持久化(Persistence)配置已启用。

运行时配置热更新。WATCH_CONTROLLER_SEMAPHORE_CONFIGMAPS(默认 true)控制 Controller 是否监听自身 ConfigMap 与信号量 ConfigMap:置为 false 后,Controller 只在启动时读取一次配置,后续变更需要手动重启才能生效(见 workflow/controller/controller.go 与 workflow/controller/controller.go)。

大工作流压缩。WORKFLOW_COMPRESSION_ALGORITHM 与 WORKFLOW_COMPRESSION_LEVEL 配合 ALWAYS_OFFLOAD_NODE_STATUS 使用,用于压缩大工作流的节点状态以控制 etcd 体积。注意压缩算法变更的兼容性约束:解压侧会自动检测算法,但旧版本无法读取新算法写入的数据,务必先升级全部组件再切换。

进度自我上报。ARGO_PROGRESS_PATCH_TICK_DURATION(默认 1m)与 ARGO_PROGRESS_FILE_TICK_DURATION(默认 3s)分别控制 Controller 将进度补丁写入 pod 注解的频率、以及 Executor 读取进度文件的频率;二者任一设为 0 都会禁用进度自我上报。这两个变量的常量定义见 workflow/common/common.go。

Controller 的 CLI 参数与 ARGO_ 前缀环境变量

原文档特别说明:Controller 的 CLI 参数都可以用带 ARGO_ 前缀的环境变量表达。转换规则是把 CLI 参数中的 - 替换为 _、全部大写,并加上 ARGO_ 前缀。例如:

workflow-controller --managed-namespace=argo

等价于:

ARGO_MANAGED_NAMESPACE=argo workflow-controller

这意味着除了上表列出的专用变量外,所有 --xxx 形式的启动参数(如 --namespaced、--configmap、--instanceid 等)都可以走环境变量注入,非常适合在容器化部署时统一管理。

在 Deployment 中为 Controller 设置环境变量

以设置 WORKFLOW_GC_PERIOD 为例,可直接修改 Controller Deployment 的容器环境变量:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: workflow-controller
spec:
  selector:
    matchLabels:
      app: workflow-controller
  template:
    metadata:
      labels:
        app: workflow-controller
    spec:
      containers:
        - env:
            - name: WORKFLOW_GC_PERIOD
              value: 30s

其中 time.Duration 类型的值必须使用 Go 的时长语法(30s、5m、1h 等),resource.Quantity 类型的值使用 Kubernetes 资源量语法(100m、256Mi 等)。

Executor 环境变量全表与配置方式

Executor(argoexec)运行在每个工作流 pod 内,负责执行模板、搬运人工制品、检查资源状态。其环境变量如下:

Name Type Default Description
ARGO_DEBUG_PAUSE_AFTER bool false 步骤执行后启用调试暂停(Debug Pause),详见 debug-pause.md。
ARGO_DEBUG_PAUSE_BEFORE bool false 步骤执行前启用调试暂停(Debug Pause),详见 debug-pause.md。
ARTIFACT_S3_UPLOAD_THREADS int 4 通过 S3 上传人工制品的线程数。
ARTIFACT_S3_UPLOAD_PART_SIZE_MIB int `` 分片上传(Multipart upload)的每片大小(MiB);默认让 MinIO 自动计算(文件 ≤ 156 GiB 时为 16 MiB)。
EXECUTOR_RETRY_BACKOFF_DURATION time.Duration 1s Executor 执行重试时的退避时长。
EXECUTOR_RETRY_BACKOFF_FACTOR float 1.6 Executor 执行重试时的退避因子。
EXECUTOR_RETRY_BACKOFF_JITTER float 0.5 Executor 执行重试时的退避抖动。
EXECUTOR_RETRY_BACKOFF_STEPS int 5 Executor 执行重试时的退避步数。
REMOVE_LOCAL_ART_PATH bool false 是否移除本地人工制品。
RESOURCE_STATE_CHECK_INTERVAL time.Duration 5s 针对指定成功/失败条件进行资源状态检查的时间间隔。

源码中的重试与调试实现

Executor 的重试退避参数在 util/retry/retry.go 的 ExecutorRetry 函数中统一读取:

func ExecutorRetry(ctx context.Context) wait.Backoff {
	steps := envutil.LookupEnvIntOr(ctx, "EXECUTOR_RETRY_BACKOFF_STEPS", 5)
	duration := envutil.LookupEnvDurationOr(ctx, "EXECUTOR_RETRY_BACKOFF_DURATION", 1*time.Second)
	factor := envutil.LookupEnvFloatOr(ctx, "EXECUTOR_RETRY_BACKOFF_FACTOR", 1.6)
	jitter := envutil.LookupEnvFloatOr(ctx, "EXECUTOR_RETRY_BACKOFF_JITTER", 0.5)
	// ...
}

按默认参数推算,5 步重试的退避序列约为 0s → 1s → 2.6s → 5.16s → 9.256s(源码注释中同样列出了该序列)。

调试暂停 ARGO_DEBUG_PAUSE_BEFORE / ARGO_DEBUG_PAUSE_AFTER 在 cmd/argoexec/commands/emissary.go 与 cmd/argoexec/commands/emissary.go 中生效:启用后 Executor 会在步骤执行前/后进入等待状态,用户可在容器内创建 /ctr/NAME_OF_THE_CONTAINER/before(或 after)文件来跳出等待、放行容器。RESOURCE_STATE_CHECK_INTERVAL 则进入 workflow/executor/executor.go 的 ResourceStateCheckInterval 字段,驱动资源模板的状态轮询。

通过 ConfigMap 为 Executor 注入环境变量

Executor 环境变量的标准注入方式不是修改 Deployment,而是在 workflow-controller-configmap 的 executor.env 段配置,Controller 会把它们注入到每个工作流 pod 中:

apiVersion: v1
kind: ConfigMap
metadata:
  name: workflow-controller-configmap
data:
  config: |
    executor:
      env:
      - name: RESOURCE_STATE_CHECK_INTERVAL
        value: 3s

该 ConfigMap 的完整结构说明见 workflow-controller-configmap.md。修改后若未开启 ConfigMap 热更新(即 WATCH_CONTROLLER_SEMAPHORE_CONFIGMAPS 被禁用),需要重启 Controller 才能生效。

Argo Server 环境变量全表与配置方式

Argo Server 提供 gRPC API、REST API 与 Web UI。其环境变量如下:

Name Type Default Description
ARGO_ARTIFACT_SERVER bool true 启用工作流归档(Workflow Archive)端点,详见 workflow-archive.md。
ARGO_PPROF bool false 启用 pprof 性能剖析端点。
ARGO_SERVER_MAX_ARTIFACT_UPLOAD_BYTES int 1073741824 输入人工制品上传端点接受的最大请求体总字节数;超限请求返回 413 Request Entity Too Large。
ARGO_SERVER_METRICS_AUTH bool true 是否在 /metrics 端点启用鉴权。
ARGO_SERVER_TOKEN_REVIEW_CACHE_TTL time.Duration 1m client 鉴权模式下 token 的 SelfSubjectReview 成功结果被记住的时长,之后才会再次咨询 API server;0 禁用缓存。
CI_ONLY_DISABLE_ARTIFACT_SERVER_CHECKS bool false 禁用人工制品插件 sidecar 的校验检查;仅用于 CI/测试。
DISABLE_VALUE_LIST_RETRIEVAL_KEY_PATTERN string "" 基于该正则表达式禁用对应键的标签值列表检索。
FIRST_TIME_USER_MODAL bool true 是否显示首次使用弹窗。
FEEDBACK_MODAL bool true 是否显示反馈弹窗。
GRPC_MESSAGE_SIZE string 104857600 为 Server 设置不同的 GRPC Max message size(支持超大工作流)。
IP_KEY_FUNC_HEADERS string "" 逗号分隔的请求头列表(如 X-Forwarded-For,X-Real-IP),用于限流时提取客户端 IP;默认使用请求的远端 IP 地址。
NEW_VERSION_MODAL bool true 是否显示新版本弹窗。
POD_NAMES string v2 pod 名是包含模板名(v2)还是节点 id(v1);必须与 Controller 设置一致。
SSO_DELEGATE_RBAC_TO_NAMESPACE bool false 启用 SSO RBAC 命名空间委托,详见 argo-server-sso.md。

Server 的 CLI 参数与 ARGO_ 前缀环境变量

与 Controller 相同,Argo Server 的 CLI 参数也可以用带 ARGO_ 前缀的环境变量表达:

argo server --managed-namespace=argo

等价于:

ARGO_MANAGED_NAMESPACE=argo argo server

注意 POD_NAMES 同时出现在 Controller 与 Server 的变量表中,原文档强调两者必须设置为相同值,否则 Controller 创建的 pod 命名策略与 Server 侧展示/查询逻辑会不一致,导致工作流节点无法正确关联。

在 Deployment 中为 Argo Server 设置环境变量

apiVersion: apps/v1
kind: Deployment
metadata:
  name: argo-server
spec:
  selector:
    matchLabels:
      app: argo-server
  template:
    metadata:
      labels:
        app: argo-server
    spec:
      containers:
        - args:
            - server
          image: quay.io/argoproj/argocli:latest
          name: argo-server
          env:
            - name: GRPC_MESSAGE_SIZE
              value: "209715200"
          ports:
          # ...

上述示例把 gRPC 最大消息大小从默认的 100 MiB(104857600 字节)提升到 200 MiB(209715200 字节),适用于节点状态巨大、单次 gRPC 响应超限的超大工作流场景。

配置实践建议与排障要点

  1. 区分 ConfigMap 与环境变量:结构化配置(如 executor.env、persistence、artifactRepository)应优先走 workflow-controller-configmap;环境变量适合实验特性、启动参数覆盖与临时调优。二者结合使用时,以文档标注为准,避免重复配置同一能力导致行为不一致。

  2. 类型与单位必须正确:time.Duration 类型(如 WORKFLOW_GC_PERIOD、ARCHIVED_WORKFLOW_GC_PERIOD)必须带 s/m/h 单位;resource.Quantity 类型(如 ARGO_AGENT_MEMORY_LIMIT)使用 Kubernetes 资源量语法。从 util/env/env.go 的实现看,解析失败会直接 panic,因此错误的取值会导致组件无法启动。

  3. 布尔开关的判定方式:部分变量是"非 false 即真"的语义(如 INDEX_WORKFLOW_SEMAPHORE_KEYS、WATCH_CONTROLLER_SEMAPHORE_CONFIGMAPS 在源码中均用 os.Getenv(...) != "false" 判断,见 workflow/controller/controller.go 与 workflow/controller/controller.go),而另一些(如 ALL_POD_CHANGES_SIGNIFICANT)是严格的 == "true" 比较(见 workflow/controller/pod/significant.go)。配置时统一写 true/false 最稳妥。

  4. 变更压缩算法前先升级全部组件:WORKFLOW_COMPRESSION_ALGORITHM 切到 zstd/brotli 后,旧版本组件将无法读取对应压缩数据,务必按 offloading-large-workflows.md 的指引规划升级顺序。

  5. 进度上报与超大工作流:若工作流规模大、pod 数量多,可适当调大 ARGO_PROGRESS_PATCH_TICK_DURATION 降低 API server 写压力,或用 WORKFLOW_COMPRESSION_* + ALWAYS_OFFLOAD_NODE_STATUS 控制节点状态体积;若单次响应超限,则调大 Server 的 GRPC_MESSAGE_SIZE。

  6. 多副本部署务必处理 leader 选举:当 Controller 以多副本部署时,保持 LEADER_ELECTION_* 系列默认值即可;如需禁用选举,必须同时把 Deployment 的滚动更新策略改为 Recreate(详见 high-availability.md),避免双主并发。

通过合理组合 Controller、Executor 与 Argo Server 三层的环境变量,可以在不改动源码的前提下完成从调度节流、垃圾回收节奏、大工作流压缩到上传并发、重试策略、限流头识别等全方位的运行时调优。配置变更后请通过 Controller 日志(wf_garbage_collector、archived_wf_garbage_collector 等组件字段)与 Prometheus 指标(如操作耗时指标)验证实际效果。

登录后查看全文
argo-workflows