Argo Workflows CLI 完全指南:argo 命令的三种连接模式、环境变量与全局参数详解
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 archive — 管理工作流归档
- argo auth — 管理认证设置
- argo cluster-template — 操作集群工作流模板
- argo completion — 输出 shell 补全代码
- argo convert — 转换工作流清单格式
- argo cp — 复制工作流工件
- argo cron — 管理定时工作流
- argo delete — 删除工作流
- argo executor-plugin — 管理执行器插件
- argo get — 显示工作流详情
- argo lint — 校验清单
- argo list — 列出工作流
- argo logs — 查看日志
- argo node — 对工作流节点执行操作
- argo resubmit — 重新提交工作流
- argo resume — 恢复工作流
- argo retry — 重试工作流
- argo server — 启动 Argo Server
- argo stop — 停止工作流(允许退出处理器运行)
- argo submit — 提交工作流
- argo suspend — 挂起工作流
- argo sync — 管理同步限制
- argo template — 操作工作流模板
- argo terminate — 立即终止工作流
- argo version — 打印版本信息
- argo wait — 等待工作流完成
- argo watch — 监视工作流直至完成
结合源码:模式选择与版本探测的实现细节
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。