Argo Workflows 的 `argo server` 命令完全指南:API Server 与 Web UI 的启动、配置与安全加固

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

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 时生效)。证书来源有两种:

  1. 通过 --tls-certificate-secret-name 指定存放证书的 Kubernetes Secret(命名空间内),源码中调用 tlsutils.GetServerTLSConfigFromSecret 加载;
  2. 未指定时自动生成自签名证书(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):

  1. 构造客户端与集群配置:读取 kube config,设置 UserAgent、QPS/Burst;创建 Dynamic、Events、Kubernetes、Workflow 四类 clientset。
  2. 准备 TLS:secure 模式下从 Secret 加载证书或生成自签名证书。
  3. 解析认证模式:将 --auth-mode 转为 auth.Modes,配置 SSO(含 logout redirect URL 校验与 RBAC 资源缓存)与 Gatekeeper。
  4. 组装服务组件:在 NewArgoServer 中创建 config controller、事件控制器、artifact server、workflow archive/offload 仓库、workflow server 等,并注册 gRPC 服务(Workflow、WorkflowTemplate、CronWorkflow、ArchivedWorkflow、ClusterWorkflowTemplate、Sync、Event 等)。
  5. 启动监听:Run 中对端口监听采用指数退避重试,随后用 gRPC-gateway 将 HTTP 请求代理到 gRPC 服务,同时挂载 /artifacts/、/oauth2/、/metrics(默认需认证,可用环境变量 ARGO_SERVER_METRICS_AUTH=false 关闭)与静态 UI 路由。

此外,容器内若配置了 artifact 插件驱动,Server 启动时还会校验各驱动镜像是否存在于 Server Pod、连接是否可用(server/apiserver/argoserver.go)。

相关文档

登录后查看全文
argo-workflows