Argo Workflows CLI 完全指南:argo 命令的三种连接模式、环境变量与全局参数详解

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

Argo Workflows CLI 完全指南:argo 命令的三种连接模式、环境变量与全局参数详解

Argo Workflows 是运行于 Kubernetes 之上的工作流引擎,其官方命令行工具 argo 是与集群交互的核心入口。本文以仓库中的 argo 根命令文档(docs/cli/argo.md)为主体,完整讲解该 CLI 支持的三种运行模式(直连 Kubernetes API、Argo Server gRPC、Argo Server HTTP/1)、全部环境变量与全局参数,并结合仓库源码(cmd/argo/main.go、cmd/argo/commands/root.go、cmd/argo/commands/client/conn.go)揭示其底层实现。读完本文,你将能根据网络环境与权限条件正确配置 argo CLI,并熟练使用其 27 个管理子命令。

CLI 概述:argo 是什么

argo 是 Argo Workflows 的命令行接口(Command Line Interface),二进制入口定义于 cmd/argo/main.go,由 Cobra 框架构建:

func main() {
	if err := commands.NewCommand().Execute(); err != nil {
		os.Exit(1)
	}
}

根命令的使用形式为:

argo [flags]

运行时它需要连接到一个后端,而这个后端可以是 Kubernetes API,也可以是 Argo Server(包括其 gRPC 或 HTTP/1 两种接口形态)。选择哪种后端,直接决定了功能边界与网络要求,这是理解 argo CLI 的第一关键点。

三种连接模式(核心)

1. Kubernetes API 模式(默认)

原理:请求直接发送给 Kubernetes API,无需部署 Argo Server。

适用场景:

  • 你对 Kubernetes API 有直接访问权限(例如在集群内或拥有有效 kubeconfig);
  • 不需要大型工作流(large workflows)或工作流归档(workflow archive)支持。

限制:由于绕过 Argo Server 的持久化与中间层,大型工作流和工作流归档在此模式下不被支持。

instance ID 注意:如果你使用了控制器实例 ID(instance ID,这种情况极为少见),需要通过环境变量显式设置:

ARGO_INSTANCEID=your-instanceid

从源码看,--instanceid 全局参数直接以 ARGO_INSTANCEID 环境变量作为默认值(见 cmd/argo/commands/client/conn.go):

cmd.PersistentFlags().StringVar(&instanceID, "instanceid", os.Getenv("ARGO_INSTANCEID"), "submit with a specific controller's instance id label. Default to the ARGO_INSTANCEID environment variable.")

2. Argo Server gRPC 模式

原理:请求通过 gRPC(基于 HTTP/2 协议)发送到 Argo Server API。

适用场景:

  • 你无法直接访问 Kubernetes API(例如你位于另一个集群中);
  • 你正在通过一个支持 HTTP/2 的网络负载均衡器访问 Argo Server。

功能增强:该模式下大型工作流和工作流归档得到支持。

限制:不支持 HTTP/2 的网络负载均衡器(如部分传统 LB)无法使用此模式。

启用方式:设置 ARGO_SERVER 环境变量:

ARGO_SERVER=localhost:2746 ;# 格式为 "host:port",不要加 "http" 或 "https" 前缀

TLS(HTTPS)场景:如果你启用了传输层安全(即运行 argo server --secure,因此走 HTTPS):

ARGO_SECURE=true

自签名证书场景:如果服务器使用自签名证书,可跳过证书校验(切勿在生产环境使用):

ARGO_INSECURE_SKIP_VERIFY=true

避免读取 kubeconfig:默认情况下,CLI 使用你的 KUBECONFIG 来确定 ARGO_TOKEN 和 ARGO_NAMESPACE 的默认值。若没有 kubeconfig,很可能报错 no configuration has been provided。要避免此问题:

KUBECONFIG=/dev/null

然后必须显式设置命名空间与令牌:

ARGO_NAMESPACE=argo
ARGO_TOKEN='Bearer ******' ;# 必须以 "Bearer " 或 "Basic " 开头

3. Argo Server HTTP/1 模式

原理:与 gRPC 模式相同,但改用普通 HTTP 协议。

适用场景:你的网络负载均衡器(如 AWS ALB)不支持 HTTP/2。

限制:argo logs --since-time=2020.... 这类带时间类型参数的命令在该模式下不可用(受限于 HTTP/1 的时间类型传输)。

启用方式:使用与 gRPC 模式相同的配置,并额外设置:

ARGO_HTTP1=true

Base HREF 场景:如果你的服务器位于带路径的 Ingress 之后(即以 argo server --base-href /argo 或 ARGO_BASE_HREF=/argo argo server 方式运行),需要设置:

ARGO_BASE_HREF=/argo

环境变量优先级与源码实现

为什么设置环境变量就能生效?核心在 cmd/argo/commands/root.go:CLI 启动时使用 Viper 自动绑定环境变量,所有 ARGO_* 前缀的环境变量都可以替代同名全局参数:

// set-up env vars for the CLI such that ARGO_* env vars can be used instead of flags
viper.AutomaticEnv()
viper.SetEnvPrefix("ARGO")
viper.SetEnvKeyReplacer(strings.NewReplacer("-", "_", ".", "_"))
// bind flags to env vars
if err := viper.BindPFlags(command.PersistentFlags()); err != nil {
	log.WithError(err).WithFatal().Error(cctx, "Failed to bind flags to env vars")
}

即:命令行 flag 优先级最高;未被显式设置的 flag 会读取同名 ARGO_* 环境变量作为默认值。例如 --argo-server ↔ ARGO_SERVER、--argo-http1 ↔ ARGO_HTTP1、--secure ↔ ARGO_SECURE、--insecure-skip-verify ↔ ARGO_INSECURE_SKIP_VERIFY、--argo-base-href ↔ ARGO_BASE_HREF。

从 cmd/argo/commands/client/conn.go 可以进一步确认每个 API 客户端相关参数的默认值来源:

参数 环境变量 默认值逻辑
--argo-server / -s ARGO_SERVER os.Getenv("ARGO_SERVER")
--argo-base-href ARGO_BASE_HREF os.Getenv("ARGO_BASE_HREF")
--argo-http1 ARGO_HTTP1 os.Getenv("ARGO_HTTP1") == "true"
--secure / -e ARGO_SECURE os.Getenv("ARGO_SECURE") != "false"(默认 true)
--insecure-skip-verify / -k ARGO_INSECURE_SKIP_VERIFY os.Getenv("ARGO_INSECURE_SKIP_VERIFY") == "true"
--instanceid ARGO_INSTANCEID os.Getenv("ARGO_INSTANCEID")

值得注意的是,--secure 的默认值是 true(即默认按 TLS 处理),而 --argo-http1、--insecure-skip-verify 默认关闭。

命名空间与令牌的解析逻辑同样体现在源码中(cmd/argo/commands/client/conn.go):

  • Namespace():优先取 kubectl 命令行覆盖(--namespace / kubeconfig 中配置的 namespace),其次读 ARGO_NAMESPACE 环境变量,最后回落到 kubeconfig 中解析出的 namespace;
  • GetAuthString():优先读 ARGO_TOKEN 环境变量,未设置时才从 kubeconfig 中提取认证信息(如 token 或 client cert)。

这一点也被单元测试直接验证(cmd/argo/commands/client/conn_test.go):

func TestGetAuthString(t *testing.T) {
	ctx := logging.TestContext(t.Context())
	t.Setenv("ARGO_TOKEN", "my-token")
	authString, err := GetAuthString(ctx)
	require.NoError(t, err)
	assert.Equal(t, "my-token", authString)
}

func TestNamespace(t *testing.T) {
	t.Setenv("ARGO_NAMESPACE", "my-ns")
	ctx := logging.TestContext(t.Context())
	assert.Equal(t, "my-ns", Namespace(ctx))
}

全局 Options 详解

以下为 argo 根命令的全部全局参数(flags),适用于所有子命令:

连接与 Argo Server 相关

参数 类型 说明
--argo-base-href string string 因 Base HREF 需要,HTTP 客户端使用的路径。默认取 ARGO_BASE_HREF 环境变量。
--argo-http1 bool 为 true 时使用 HTTP 客户端。默认取 ARGO_HTTP1 环境变量。
-s, --argo-server host:port string API 服务器地址,格式 host:port,如 localhost:2746。默认取 ARGO_SERVER 环境变量。
-e, --secure bool 服务器是否对 Argo Server 使用 TLS。默认取 ARGO_SECURE 环境变量(默认 true)。
-k, --insecure-skip-verify bool 为 true 时不校验 Argo Server 证书有效性,会使 HTTPS 连接不安全。默认取 ARGO_INSECURE_SKIP_VERIFY 环境变量。
-H, --header strings stringSlice 为 Argo CLI 发出的所有请求附加额外的 Header(可重复多次,也支持逗号分隔的多个 Header)。仅当 ARGO_HTTP1 或 --argo-http1 为 true 时生效。
--instanceid string string 以特定控制器的 instance id 标签提交。默认取 ARGO_INSTANCEID 环境变量。

Kubernetes / kubeconfig 相关

参数 类型 说明
--kubeconfig string string kube config 文件路径,仅在集群外(out-of-cluster)时需要。
--as string string 用于该操作所模拟(impersonate)的用户名。
--as-group stringArray stringArray 模拟操作的用户组,可重复指定多个组。
--as-uid string string 模拟操作的 UID。
--cluster string string 要使用的 kubeconfig cluster 名称。
--context string string 要使用的 kubeconfig context 名称。
--user string string 要使用的 kubeconfig user 名称。
-n, --namespace string string 本次 CLI 请求的命名空间作用域。
--certificate-authority string string CA 证书文件路径。
--client-certificate string string TLS 客户端证书文件路径。
--client-key string string TLS 客户端密钥文件路径。
--insecure-skip-tls-verify bool 为 true 时不校验服务器证书有效性,会使 HTTPS 连接不安全。
--tls-server-name string string 用于校验服务器证书的名称;未提供时使用连接服务器的主机名。
--server string string Kubernetes API 服务器的地址与端口。
--token string string 访问 API 服务器的 Bearer token。
--username string string 访问 API 服务器的基础认证用户名。
--password string string 访问 API 服务器的基础认证密码。
--proxy-url string string 若提供,将通过该 URL 代理连接。
--request-timeout string string 单个服务器请求超时时间。非零值需带时间单位(如 1s、2m、3h),零值表示不超时(默认 "0")。
--disable-compression bool 为 true 时,对所有服务器请求关闭响应压缩。

日志相关

参数 类型 说明
--log-format string string 日志格式,取值为 text 或 json(默认 "text")。
--loglevel string string 日志级别,取值为 debug、info、warn、error(默认 "info")。
--gloglevel int int 设置 glog 日志级别。
-v, --verbose bool 开启详细日志,等价于 --loglevel debug。

从 cmd/argo/commands/root.go 可以看到,--verbose 的实现是将其映射为 debug 级别并同步提升 glog 级别:

command.PersistentPreRun = func(cmd *cobra.Command, args []string) {
	if verbose {
		logLevel = "debug"
		glogLevel = 6
	}
	...
}
command.PersistentFlags().StringVar(&logLevel, "loglevel", "info", "Set the logging level. One of: debug|info|warn|error")
command.PersistentFlags().BoolVarP(&verbose, "verbose", "v", false, "Enabled verbose logging, i.e. --loglevel debug")

另外,CLI 在每次命令执行后(PersistentPostRun)会检查客户端与服务器版本是否匹配并输出警告(cmd/argo/commands/root.go):

command.PersistentPostRun = func(cmd *cobra.Command, args []string) {
	cmdutil.PrintVersionMismatchWarning(cmd.Context(), argo.GetVersion(), grpcutil.LastSeenServerVersion)
}

子命令全景

argo 通过 Cobra 注册了 27 个子命令(见 cmd/argo/commands/root.go),覆盖工作流生命周期的方方面面。下面按用途归类,完整列出:

工作流生命周期管理

子命令 说明
argo submit 提交一个工作流
argo get 显示工作流详情
argo list 列出工作流
argo logs 查看 Pod 或工作流的日志
argo watch 监视工作流直到其完成
argo wait 等待工作流完成
argo delete 删除工作流
argo resubmit 重新提交一个或多个工作流
argo resume 恢复一个或多个工作流(suspend 的反操作)
argo retry 重试一个或多个工作流
argo stop 停止一个或多个工作流,允许所有退出处理器(exit handlers)运行
argo suspend 挂起一个或多个工作流(resume 的反操作)
argo terminate 立即终止一个或多个工作流
argo node 对工作流中的某个节点执行操作

模板与配置管理

子命令 说明
argo template 操作工作流模板(workflow templates)
argo cluster-template 操作集群级工作流模板(cluster workflow templates)
argo cron 管理定时工作流(cron workflows)
argo archive 管理工作流归档(workflow archive)
argo sync 管理同步限制(sync limits)
argo lint 校验清单文件或目录
argo convert 将工作流清单从旧格式转换为当前格式

其他

子命令 说明
argo auth 管理认证设置
argo cp 从工作流复制工件(artifacts)
argo server 启动 Argo Server
argo executor-plugin 管理执行器插件(executor plugins)
argo completion 为指定 shell(bash、zsh 或 fish)输出 shell 补全代码
argo version 打印版本信息

各子命令的详细用法可参阅 docs/cli 目录下的对应文档,例如:

结合源码:模式选择与版本探测的实现细节

argo version 是一个能直观体现三种模式差异的命令(cmd/argo/commands/version.go):当设置了 ARGO_SERVER 时,它还会额外连接服务器查询并打印 argo-server 的版本:

if _, ok := os.LookupEnv("ARGO_SERVER"); ok {
	ctx, apiClient, err := client.NewAPIClient(cmd.Context())
	...
	serverVersion, err := serviceClient.GetVersion(ctx, &infopkg.GetVersionRequest{})
	cmdutil.PrintVersion("argo-server", *serverVersion, short)
}

而 NewAPIClient(cmd/argo/commands/client/conn.go)负责把参数组装成统一的 API 客户端,其行为要点包括:

  • 复用 kubectl 的客户端证书参数(--client-certificate / --client-key 必须成对提供,否则报错 --client-certificate and --client-key must be provided together,这一点同样有单元测试覆盖,见 conn_test.go);
  • 支持通过 --proxy-url 设置代理;
  • 认证字符串通过 GetAuthString 惰性获取(优先 ARGO_TOKEN,回落到 kubeconfig),命名空间通过 Namespace 解析。

实战:典型配置示例

场景一:集群内直接使用(Kubernetes API 模式)

export KUBECONFIG=/path/to/kubeconfig
export ARGO_NAMESPACE=argo
argo list

场景二:跨集群 + Argo Server gRPC(支持大型工作流与归档)

export KUBECONFIG=/dev/null
export ARGO_SERVER=argo-server.example.com:2746
export ARGO_NAMESPACE=argo
export ARGO_SECURE=true
export ARGO_TOKEN='Bearer ******'
argo get my-workflow

场景三:不支持 HTTP/2 的负载均衡器(HTTP/1 模式)

export ARGO_SERVER=argo-server.example.com:2746
export ARGO_NAMESPACE=argo
export ARGO_SECURE=true
export ARGO_HTTP1=true
export ARGO_BASE_HREF=/argo   # 若服务器部署在带路径的 Ingress 之后
argo logs my-workflow

注意:HTTP/1 模式下 argo logs --since-time=... 因时间类型传输限制不可用。

常见问题排查

现象 原因与对策
报错 no configuration has been provided 默认模式会读取 KUBECONFIG;若无 kubeconfig,设置 KUBECONFIG=/dev/null 并显式设置 ARGO_NAMESPACE 与 ARGO_TOKEN
ARGO_TOKEN 不生效 令牌必须以 Bearer 或 Basic 开头,且注意 kubeconfig 存在时其认证信息会被优先采用——需同时处理 KUBECONFIG
连接 Argo Server 报 TLS 错误 检查 ARGO_SECURE=true(默认即 true);自签名证书仅测试环境可设 ARGO_INSECURE_SKIP_VERIFY=true,生产禁用
负载均衡器不支持 HTTP/2 改用 ARGO_HTTP1=true,必要时配合 ARGO_BASE_HREF
客户端与服务器版本不一致 运行 argo version 对比本地与服务器版本(设置 ARGO_SERVER 时会输出服务器版本),参考 docs/releases.md 匹配版本

小结

argo CLI 的三种模式对应了从"直接面对 Kubernetes API"到"通过 Argo Server 获得大型工作流与归档能力"的不同部署形态;ARGO_* 环境变量与同名全局参数一一对应,优先级为 命令行 flag > 环境变量 > kubeconfig 推断,这一机制在 cmd/argo/commands/root.go 与 cmd/argo/commands/client/conn.go 中均有明确实现,并有单元测试佐证。掌握模式选择与环境变量配置,即可在任何网络拓扑下可靠地驱动 Argo Workflows。

登录后查看全文
argo-workflows