Argo Workflows 的 `argo server` 命令完全指南:API Server 与 Web UI 的启动、配置与安全加固
Argo Workflows 的 argo server 命令完全指南:API Server 与 Web UI 的启动、配置与安全加固
Argo Server 是 Argo Workflows 暴露给用户的 API 与 Web UI 服务层,支持以 "hosted"(托管)与 "local"(本地)两种模式运行,是大规模工作流(offload)与工作流归档(archive)等能力的必要组件。本文以 argo server 命令为主线,完整讲解其全部命令行参数、TLS、认证模式、托管命名空间、反向代理部署与限流安全配置,并结合仓库源码给出底层实现依据。
命令概览
argo server 用于启动 Argo Server,其基本用法为:
argo server [flags]
命令的 Short 描述为 “start the Argo Server”,定义位于 cmd/argo/commands/server.go。该命令实际会把配置组装为 apiserver.ArgoServerOpts,最终调用 apiserver.NewArgoServer(...) 与 server.Run(ctx, port, browserOpenFunc) 完成服务启动。
⚠️ HTTP 与 HTTPS 的默认差异:Argo Server 默认监听 HTTPS 请求(
--secure默认为true),而非 HTTP。若在--secure=false的“不安全模式”下运行,服务会打印警告并提示参考 TLS 文档。
两种运行模式
Hosted Mode(托管模式)
适合以下场景:
- 需要一个可直接替换 Argo UI 的部署;
- 需要防止用户直接访问底层数据库。
托管模式作为标准部署清单的一部分提供,对应 manifests/base/argo-server/argo-server-deployment.yaml,其中 Deployment 以 args: <a href="https://link.gitcode.com/i/5bb12151d10668f2547d674dc0554dbe" target="_blank"> server ] 启动容器,监听 2746 端口并配置了 HTTPS 的 readinessProbe;配套的 Service 定义在 [manifests/base/argo-server/argo-server-service.yaml(argo-server Service,端口 2746)。由于该模式下 Argo Server 不直接写数据库,因此可以始终开启工作流归档(archive)与大工作流节点卸载(offload)的读取能力(见 server/apiserver/argoserver.go 中 persist.NewOffloadNodeStatusRepo 与 persist.NewWorkflowArchive 的创建逻辑)。
Local Mode(本地模式)
适合以下场景:
- 需要一个无需复杂部署的轻量方案;
- 不需要运行数据库。
直接执行:
argo server
即可在本机 2746 端口启动服务,随后访问 https://localhost:2746。本地模式下若未指定 --tls-certificate-secret-name,服务会自动生成自签名 TLS 证书(源码见 cmd/argo/commands/server.go 中 tlsutils.GenerateX509KeyPairTLSConfig 的调用)。如需浏览器自动打开 UI,可加 -b/--browser 标志(仅本地模式有效),源码中通过 github.com/pkg/browser 打开 URL(cmd/argo/commands/server.go)。
全部 Options 参数详解
argo server 的独立参数定义于 cmd/argo/commands/server.go,下表为完整清单:
| 参数 | 类型/默认值 | 说明 |
|---|---|---|
--access-control-allow-origin |
string,默认空 | 在 HTTP 响应中设置 Access-Control-Allow-Origin 头 |
--allowed-link-protocol |
stringArray,默认 [http,https] |
links 功能允许的协议白名单 |
--api-rate-limit |
uint,默认 1000 |
按 IP 的 API 限流上限(每秒) |
--auth-mode |
stringArray,默认 [client] |
API Server 认证模式,可为 client、server、sso 的任意 1 个或多个组合 |
--base-href |
string,默认 / |
index.html 中 base href 的值;用于反向代理子路径(如 /argo)场景 |
-b, --browser |
bool,默认 false | 自动打开浏览器(本地模式) |
--configmap |
string,默认 workflow-controller-configmap |
读取 workflow controller 配置的 K8s ConfigMap 名称 |
--event-async-dispatch |
bool,默认 false | 事件异步分发 |
--event-operation-queue-size |
int,默认 16 |
事件操作队列容量 |
--event-worker-count |
int,默认 4 |
事件 worker 数量 |
-h, --help |
- | server 命令帮助 |
--hsts |
bool,默认 true |
是否添加 HTTP Strict Transport Security 头(仅在开启 secure 时生效) |
--kube-api-burst |
int,默认 30 |
与 kube-apiserver 通信的 Burst |
--kube-api-qps |
float32,默认 20 |
与 kube-apiserver 通信的 QPS |
--log-format |
string,默认 text |
日志格式:text 或 json |
--loglevel |
string,默认 info |
日志级别:debug、info、warn、error |
--managed-namespace |
string,默认空 | 监听的命名空间,默认使用安装命名空间 |
--namespaced |
bool,默认 false | 以命名空间(namespaced)模式运行 |
-p, --port |
int,默认 2746 |
监听端口 |
-e, --secure |
bool,默认 true |
是否监听 TLS |
--tls-certificate-secret-name |
string,默认空 | 存放服务器证书的 Kubernetes Secret 名称 |
--x-frame-options |
string,默认 DENY |
在 HTTP 响应中设置 X-Frame-Options 头 |
Options inherited from parent commands(继承自父命令)
argo server 还继承了一组用于配置 API 客户端与 Kubernetes 访问的父级参数:
--argo-base-href string 与 HTTP 客户端配合使用的 Base HREF 路径,默认取 ARGO_BASE_HREF 环境变量
--argo-http1 使用 HTTP 客户端,默认取 ARGO_HTTP1 环境变量
-s, --argo-server host:port API server 地址,如 localhost:2746,默认取 ARGO_SERVER 环境变量
--as string 模拟(impersonate)执行操作的用户名
--as-group stringArray 模拟的用户组,可重复指定多个
--as-uid string 模拟的 UID
--certificate-authority string CA 证书文件路径
--client-certificate string 客户端证书文件路径
--client-key string 客户端私钥文件路径
--cluster string kubeconfig 中要使用的 cluster 名称
--context string kubeconfig 中要使用的 context 名称
--disable-compression 关闭对服务端请求的响应压缩
--gloglevel int glog 日志级别
-H, --header strings 为所有请求附加的额外 Header(可重复,也支持逗号分隔),仅在 ARGO_HTTP1 或 --argo-http1 为 true 时生效
--insecure-skip-tls-verify 不校验服务器证书有效性(会使 HTTPS 连接不安全)
-k, --insecure-skip-verify 不校验 Argo Server 证书有效性,默认取 ARGO_INSECURE_SKIP_VERIFY 环境变量
--instanceid string 以指定控制器的 instance id 标签提交,默认取 ARGO_INSTANCEID 环境变量
--kubeconfig string kube config 路径(集群外使用时必须)
-n, --namespace string 本次 CLI 请求的命名空间作用域
--password string API server 基础认证密码
--proxy-url string 通过指定 URL 代理连接
--request-timeout string 单次服务器请求的超时时间(如 1s、2m、3h),0 表示不超时(默认 "0")
--server string Kubernetes API server 的地址与端口
--tls-server-name string 校验服务器证书使用的名称,缺省时使用连接主机名
--token string Bearer token 认证
--user string kubeconfig 中要使用的用户名称
-v, --verbose 启用详细日志(等价于 --loglevel debug)
值得说明的是,父命令参数中带“默认取 ARGO_* 环境变量”的项,对应 cmd/argo/commands/server.go 中基于 spf13/viper 的 ARGO 环境变量前缀绑定机制:所有 flag 都可以用 ARGO_ 前缀的对应环境变量(- 与 . 替换为 _)覆盖。
关键配置深入解析
认证模式 --auth-mode
Argo Server 不直接做认证,而是把认证委托给 Kubernetes API Server(client 模式)或 OAuth Provider(sso 模式)。三种模式的语义(参见 docs/argo-server-auth-mode.md):
server:托管模式下使用 Server 的 Service Account;本地模式下使用本机 kube config。client:使用客户端的 Kubernetes bearer token,Server 在响应请求前通过SelfSubjectReview校验 token,因此该模式要求 Kubernetes 1.28 及以上;校验结果会按ARGO_SERVER_TOKEN_REVIEW_CACHE_TTL(默认1m)缓存以降低 API server 压力。sso:使用单点登录(参见 docs/argo-server-sso.md),RBAC 默认与server模式共用同一个 Service Account,除非启用了 SSO RBAC。
v3.0 起默认模式为 client(v3.0 之前为 server)。可通过重复传参组合多个模式,例如:
argo server --auth-mode=sso --auth-mode=client
从源码看,cmd/argo/commands/server.go 会逐个将模式加入 auth.Modes,并在“仅启用 server 模式”时打印“运行在没有客户端认证”的警告。若启用 sso 模式,server/apiserver/argoserver.go 中会额外校验 sso.logoutRedirectUrl 的合法性、创建 SSO 服务,并在启用 SSO RBAC 时启动用于 RBAC 的资源缓存。
托管命名空间 --namespaced 与 --managed-namespace
Argo Workflows 既可按命名空间隔离(安装 Role)也可按集群范围(安装 ClusterRole)部署。命名空间隔离部署时,Workflow Controller 与 Argo Server 都必须加 --namespaced;如需在工作流运行的其他命名空间工作,还需加 --managed-namespace(集群范围部署则不要加这两个参数)。典型示例(详见 docs/managed-namespace.md):
- args:
- --configmap
- workflow-controller-configmap
- --executor-image
- quay.io/argoproj/workflow-controller:v3.6.7
- --namespaced
- --managed-namespace
- default
适用场景:例如 Argo 安装在某命名空间,而数据科学团队在工作流专用命名空间 data-science-workflows 中运行工作流,即可用 managed namespace 安装,避免把安装命名空间的权限授予普通用户。源码中的处理逻辑位于 cmd/argo/commands/server.go:非 namespaced 时忽略 --managed-namespace 并告警;namespaced 但未指定 managed namespace 时,将其回退为安装命名空间;SSO 相关资源则从 managed namespace 中读取。
Base HREF --base-href
当 Server 位于反向代理的子路径(如 /argo)而非根路径时,可用 --base-href flag 或 ARGO_BASE_HREF 环境变量设置子路径。该值会写入 index.html 的 base href,同时影响静态资源与 API 路由的解析(参见 docs/argo-server.md 的 Base HREF 小节)。
传输层安全 TLS
--secure 默认开启 TLS,--hsts 默认开启 HSTS(仅在 secure 时生效)。证书来源有两种:
- 通过
--tls-certificate-secret-name指定存放证书的 Kubernetes Secret(命名空间内),源码中调用tlsutils.GetServerTLSConfigFromSecret加载; - 未指定时自动生成自签名证书(
tlsutils.GenerateX509KeyPairTLSConfig)。
TLS 最低版本默认 TLS1.2,可通过环境变量 TLS_MIN_VERSION 调整(cmd/argo/commands/server.go)。完整安全配置参见 docs/tls.md。
日志与运行参数
--loglevel:debug/info/warn/error,默认info;-v/--verbose等价于--loglevel debug。--log-format:text或json,默认text。--kube-api-qps(默认 20)与--kube-api-burst(默认 30):控制与 kube-apiserver 通信的速率,对应restclient.Config的QPS/Burst字段(cmd/argo/commands/server.go)。- 事件处理相关:
--event-operation-queue-size(默认 16)、--event-worker-count(默认 4)、--event-async-dispatch,这些参数传给event.NewController控制事件的分发吞吐(server/apiserver/argoserver.go)。 --configmap:指定读取 controller 配置(如归档、持久化、SSO、artifact repository 等)的 ConfigMap,默认workflow-controller-configmap。
另外,gRPC 消息大小上限由环境变量 GRPC_MESSAGE_SIZE 控制(默认 100MB,server/apiserver/argoserver.go),超过时应优先使用分页。
访问 Argo Workflows UI
默认情况下 Argo UI Service 不暴露外部 IP,可通过以下三种方式访问(详见 docs/argo-server.md)。
方式一:kubectl port-forward
kubectl -n argo port-forward svc/argo-server 2746:2746
注意:如果使用 Helm chart 安装(argo-workflows chart),Service 名称应为
svc/argo-workflows-server而非svc/argo-server。
然后访问 https://localhost:2746。
方式二:暴露 LoadBalancer
将 Service 类型改为 LoadBalancer:
kubectl patch svc argo-server -n argo -p '{"spec": {"type": "LoadBalancer"}}'
等待外部 IP 就绪:
kubectl get svc argo-server -n argo
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
argo-server LoadBalancer 10.43.43.130 172.18.0.2 2746:30008/TCP 18h
方式三:Ingress
首先给 deployment/argo-server 增加 ARGO_BASE_HREF 环境变量(务必以 / 结尾):
---
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
env:
- name: ARGO_BASE_HREF
value: /argo/
image: quay.io/argoproj/argocli:latest
name: argo-server
...
然后创建 Ingress,并添加 ingress.kubernetes.io/rewrite-target 注解:
由于默认开启了 TLS,必须让 Ingress Controller 知道后端使用 HTTPS。不同 Controller 的写法不同:例如 Traefik 使用
ingress.kubernetes.io/protocol注解,而 ingress-nginx 使用nginx.ingress.kubernetes.io/backend-protocol。
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: argo-server
annotations:
ingress.kubernetes.io/rewrite-target: /$2
ingress.kubernetes.io/protocol: https # Traefik
nginx.ingress.kubernetes.io/backend-protocol: https # ingress-nginx
spec:
rules:
- http:
paths:
- path: /argo(/|$)(.*)
pathType: Prefix
backend:
service:
name: argo-server
port:
number: 2746
安全考量
Argo Server 官方文档(docs/argo-server.md 的 Security 章节)对部署者给出如下安全建议:
API 认证限流
Argo Server 自身不执行认证,而是委托给 Kubernetes API Server(--auth-mode=client)或 OAuth Provider(--auth-mode=sso)。因此推荐由被委托方实现所需的认证限流策略。
IP 地址日志
Argo Server 不记录 API 请求的 IP 地址。建议将 Argo Server 置于负载均衡器之后,并由负载均衡器记录返回认证/授权错误的请求来源 IP。
内置限流(Rate Limiting)
v3.4 及以后版本可用。
Argo Server 默认按 IP 每秒限流 1000 次,可通过 --api-rate-limit 调整。底层实现基于 sethvargo/go-limiter 的 memorystore 与 httplimit 中间件:内存令牌桶以 1 秒为窗口(server/apiserver/argoserver.go),默认以客户端 IP 作为限流键,也可通过环境变量 IP_KEY_FUNC_HEADERS(逗号分隔的 header 名列表)改为依据指定 Header 计算键(server/apiserver/argoserver.go)。限流信息通过以下响应头暴露:
X-Rate-Limit-Limit:适用于当前请求的限流上限;X-Rate-Limit-Remaining:当前限流窗口内剩余请求数;X-Rate-Limit-Reset:限流重置时间(UTC);Retry-After:客户端应在何时重试(限流过期时间,UTC)。
从 gRPC 层看,grpcutil.RatelimitUnaryServerInterceptor 与 RatelimitStreamServerInterceptor 被同时挂载在 gRPC 拦截器链上(server/apiserver/argoserver.go),因此 REST(grpc-gateway)与 gRPC 两种接入方式都受到限流保护。
其他响应头安全
--x-frame-options(默认DENY):通过X-Frame-Options头防止 UI 被嵌入第三方页面(点击劫持防护)。--access-control-allow-origin:按需开放跨域访问。--hsts(默认 true):secure 模式下注入 HSTS 头,强制浏览器使用 HTTPS。--allowed-link-protocol(默认<a href="https://link.gitcode.com/i/1d3e05d93d816bf33b9c1f0ae728b828" target="_blank">http,https]):限制 UI 中 links 功能可跳转的协议,避免javascript:等危险协议(配置加载后由config.Sanitize(...)校验,见 [server/apiserver/argoserver.go)。
从源码理解启动流程
argo server 的启动链路可以概括为(对应文件 cmd/argo/commands/server.go 与 server/apiserver/argoserver.go):
- 构造客户端与集群配置:读取 kube config,设置 UserAgent、QPS/Burst;创建 Dynamic、Events、Kubernetes、Workflow 四类 clientset。
- 准备 TLS:secure 模式下从 Secret 加载证书或生成自签名证书。
- 解析认证模式:将
--auth-mode转为auth.Modes,配置 SSO(含 logout redirect URL 校验与 RBAC 资源缓存)与 Gatekeeper。 - 组装服务组件:在
NewArgoServer中创建 config controller、事件控制器、artifact server、workflow archive/offload 仓库、workflow server 等,并注册 gRPC 服务(Workflow、WorkflowTemplate、CronWorkflow、ArchivedWorkflow、ClusterWorkflowTemplate、Sync、Event 等)。 - 启动监听:
Run中对端口监听采用指数退避重试,随后用 gRPC-gateway 将 HTTP 请求代理到 gRPC 服务,同时挂载/artifacts/、/oauth2/、/metrics(默认需认证,可用环境变量ARGO_SERVER_METRICS_AUTH=false关闭)与静态 UI 路由。
此外,容器内若配置了 artifact 插件驱动,Server 启动时还会校验各驱动镜像是否存在于 Server Pod、连接是否可用(server/apiserver/argoserver.go)。