Argo Workflows 的 Argo Server:架构、部署模式与安全配置全指南

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

Argo Workflows 的 Argo Server:架构、部署模式与安全配置全指南

Argo Server 是 Argo Workflows 中负责对外提供 API 与 Web UI 的服务端组件,它让用户可以在浏览器中查看、提交和管理工作流,也是使用大型工作流卸载与工作流归档功能的前提。本文将以官方文档为骨架,结合仓库内 server/apiserver/argoserver.go 与 manifests/base/argo-server/argo-server-deployment.yaml 等源码与清单文件,系统讲解 Argo Server 的两种运行模式、启动参数、UI 访问方式(端口转发 / LoadBalancer / Ingress)以及安全加固要点,帮助你按生产需求正确部署与运维 Argo Server。

Argo Server 是什么

Argo Server 是一个暴露工作流 API 与 UI 的服务端程序,它取代了旧版的 Argo UI。它的职责包括:

  • 通过 gRPC + HTTP/gRPC-Gateway 对外暴露 Workflow、CronWorkflow、WorkflowTemplate、ClusterWorkflowTemplate、ArchivedWorkflow、EventSource、Sensor 等资源的管理 API;
  • 提供基于浏览器的 Argo Workflows UI;
  • 提供产物(artifact)下载/上传的 HTTP 接口;
  • 在你需要大型工作流卸载(把超出 Etcd 1MB 限制的节点状态压缩后存入 SQL 数据库)或工作流归档(长期保存已完成工作流)时,它是访问这些数据所必需的组件。

从源码结构看,Argo Server 启动时会在 argoserver.go 的 Run 方法中依次完成:读取 workflow-controller 配置(--configmap 指定的 ConfigMap)、初始化实例 ID 服务、按 persistence 配置创建节点状态卸载仓库(OffloadNodeStatusRepo)与工作流归档仓库(WorkflowArchive)、创建各业务服务端,最后启动一个同时支持 HTTP/1.1 与 HTTP/2(含明文 h2c)的监听器。因此它不仅是 UI 入口,也是大型工作流读取、历史工作流检索的唯一入口。

Hosted Mode(托管模式)

当满足以下条件时,推荐使用托管模式:

  • 你希望将其作为 Argo UI 的直接替代品(drop-in replacement);
  • 你需要防止用户直接访问数据库。

托管模式下,Argo Server 以 Deployment 形式运行在 Kubernetes 集群内,使用专用的 ServiceAccount(argo-server),由集群 RBAC 控制其权限,用户通过 API 访问,而非直接接触数据库。

该模式随标准安装清单提供,核心清单为 manifests/base/argo-server/argo-server-deployment.yaml,同目录下还包含 argo-server-service.yaml(Service)与 argo-server-sa.yaml(ServiceAccount)。Deployment 的关键配置如下:

# manifests/base/argo-server/argo-server-deployment.yaml(节选)
apiVersion: apps/v1
kind: Deployment
metadata:
  name: argo-server
spec:
  selector:
    matchLabels:
      app: argo-server
  template:
    metadata:
      labels:
        app: argo-server
    spec:
      serviceAccountName: argo-server
      containers:
        - name: argo-server
          image: quay.io/argoproj/argocli:latest
          securityContext:
            readOnlyRootFilesystem: true
            runAsNonRoot: true
            allowPrivilegeEscalation: false
            capabilities:
              drop: [ALL]
          args: [ server ]
          ports:
            - name: web
              containerPort: 2746
          readinessProbe:
            httpGet:
              port: 2746
              scheme: HTTPS   # 默认以 HTTPS 提供服务
              path: /
            initialDelaySeconds: 10
            periodSeconds: 20

几点值得注意:

  • 容器镜像为 quay.io/argoproj/argocli:latest,启动参数为 server(对应 cmd/argo/commands/server.go 中的 NewServerCommand);
  • 默认监听 2746 端口;
  • 就绪探针使用 HTTPS 协议,印证了官方文档开头的警告:默认情况下 Argo Server 监听 HTTPS 请求,而非 HTTP;
  • 采用只读根文件系统、非 root 用户、禁止提权并丢弃全部 capabilities 的加固安全上下文。

Local Mode(本地模式)

当你希望快速体验、不需要复杂部署或数据库时,可使用本地模式:

  • 无需额外搭建;
  • 不需要运行数据库。

本地运行只需一条命令:

argo server

该命令会在本机 2746 端口启动服务,访问 https://localhost:2746 即可打开 UI。注意此时使用的是你本地的 kube config 进行认证。若想启动后自动打开浏览器,可加 --browser(-b)标志,对应源码 server.go 中的 enableOpenBrowser 选项。

常用启动选项

Argo Server 的绝大多数选项既可以用命令行 flag 传入,也可以通过 ARGO_ 前缀的环境变量传入(源码中通过 viper.SetEnvPrefix("ARGO") 将 flag 与 ARGO_* 环境变量绑定,见 server.go)。

端口

argo server --port 2746

默认端口为 2746,对应 -p 标志(server.go)。

认证模式(Auth Mode)

认证模式的完整说明见 docs/argo-server-auth-mode.md。可选值:

  • server:托管模式下使用 Server 自身的 ServiceAccount,本地模式下使用本地 kube config;
  • client:使用客户端的 Kubernetes bearer token,Server 会通过 Kubernetes 的 SelfSubjectReview 校验 token,此模式需要 Kubernetes 1.28 及以上;校验结果按 ARGO_SERVER_TOKEN_REVIEW_CACHE_TTL(默认 1m)缓存;
  • sso:使用单点登录,见 docs/argo-server-sso.md。

v3.0 之后默认值为 client(v3.0 之前为 server)。可同时启用多个模式:

argo server --auth-mode=sso --auth-mode=client

托管命名空间(Managed Namespace)

见 docs/managed-namespace.md。通过 --namespaced 与 --managed-namespace 配合使用,限定 Server 只管理特定命名空间。

Base HREF

当 Server 位于反向代理的子路径下(例如 /argo)时,可通过 --base-href 标志或 ARGO_BASE_HREF 环境变量设置替代子路径。源码中默认值为 /,flag 定义为 --base-href(server.go)。该值会注入到 UI 的 index.html 与 SSO 回调等场景中(见 argoserver.go 中 baseHRef 字段的使用)。

登出重定向 URL(Logout Redirect URL)

v4.2 及以后

配置 SSO 登出后的重定向地址,详见 docs/argo-server-sso.md。源码中 Server 启动时会调用 logout.ValidateRedirectURL 校验该地址,非法则直接报错退出(见 argoserver.go)。

传输层安全(TLS)

默认启用 TLS,详见 docs/tls.md。相关标志:

  • --secure / -e:是否监听 TLS,默认 true;
  • --tls-certificate-secret-name:存放服务器证书的 Kubernetes Secret 名称;为空时 Server 会自动生成自签名证书(server.go);
  • --hsts:是否添加 HTTP Strict Transport Security 头,默认 true,仅在安全模式下生效;
  • TLS_MIN_VERSION 环境变量:TLS 最低版本,默认 TLS1.2。

SSO

见 docs/argo-server-sso.md;关于与 Argo CD 共享 Dex 的配置见 docs/argo-server-sso-argocd.md。

其他常用标志(来自源码 server.go)

Flag 默认值 说明
--configmap workflow-controller-configmap 获取 workflow-controller 配置的 ConfigMap 名称
--event-operation-queue-size 16 事件操作队列容量
--event-worker-count 4 事件 worker 数量
--event-async-dispatch false 是否异步分发事件
--x-frame-options DENY 设置 HTTP 响应的 X-Frame-Options 头
--access-control-allow-origin 空 设置 Access-Control-Allow-Origin 头
--api-rate-limit 1000 每个 IP 的 API 限流阈值(每秒)
--allowed-link-protocol http,https links 功能允许的协议
--kube-api-qps / --kube-api-burst 20 / 30 与 kube-apiserver 通信的 QPS 与 Burst
--loglevel info 日志级别:debug|info|warn|error
--log-format text 日志格式:text|json

访问 Argo Workflows UI

默认情况下,Argo UI 的 Service 不会暴露外部 IP。可通过以下三种方式访问:

方式一:kubectl port-forward

kubectl -n argo port-forward svc/argo-server 2746:2746

然后访问 https://localhost:2746。

注意:若使用 Helm chart 安装,请将 Service 名称替换为 svc/argo-workflows-server。

方式二:暴露为 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(含子路径部署)

如果希望通过 Ingress 以子路径(如 /argo)访问,需要先给 deployment/argo-server 添加 ARGO_BASE_HREF 环境变量。不要忘记以 / 结尾:

# 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
        env:
          - name: ARGO_BASE_HREF
            value: /argo/
        image: quay.io/argoproj/argocli:latest
        name: argo-server
...

然后创建 Ingress,并添加注解 ingress.kubernetes.io/rewrite-target: /:

由于默认启用 TLS,必须告知 Ingress 控制器后端使用 HTTPS。具体方式因控制器而异:例如 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

子路径下访问 UI 的详细讨论可参考仓库中与之相关的 issue(#3080)。

为什么需要 Argo Server:大型工作流卸载与工作流归档

Argo Server 的两大核心增强场景值得展开说明。

大型工作流卸载(Offloading Large Workflows)

Argo 将工作流存储为 Kubernetes 资源(即保存在 Etcd 中),而 Etcd 对单个资源有 1MB 的大小限制。每个节点的状态都保存在 /status/nodes 字段中,很容易超过 1MB。当超限时,Argo 会尝试压缩节点状态存入 /status/compressedNodes;若仍然过大,则存入 SQL 数据库。

启用方式是在配置文件的 persistence 下配置 Postgres、MySQL 或 MariaDB,并设置 nodeStatusOffLoad: true。详细说明见 docs/offloading-large-workflows.md。

从 argoserver.go 可以看到:Argo Server 启动时若检测到 persistence 配置,就会创建 OffloadNodeStatusRepo 与 WorkflowArchive。源码注释明确指出,Argo Server 对卸载仓库与归档仓库是"只读"的——即使控制器关闭了卸载/归档,Server 依然可以读取历史记录。这正是"使用大型工作流卸载或工作流归档功能时必须部署 Argo Server"的原因。

工作流归档(Workflow Archive)

若希望长期保留已完成的工作流,可将它们归档到 Postgres(>=9.4)、MySQL(>=5.7.8)或 MariaDB(>=10.2)数据库,归档内容包含工作流状态、执行过的 Pod 及结果,但不包含 Pod 日志——如需保存日志,必须按 docs/configure-artifact-repository.md 配置产物仓库。完整说明见 docs/workflow-archive.md。

安全加固要点

在生产环境中部署 Argo Server 时,需要关注以下安全事项:

API 认证限流(Authentication Rate Limiting)

Argo Server 本身不直接执行认证,而是将认证委托给:

  • Kubernetes API Server(--auth-mode=client 时);
  • OAuth Provider(--auth-mode=sso 时)。

因此,建议由受托管的认证方来实现你所需的认证限流策略。

IP 地址日志(IP Address Logging)

Argo Server 不会记录 API 请求的 IP 地址。建议将 Argo Server 置于负载均衡器之后,并让负载均衡器记录返回认证/授权错误的请求的 IP 地址,用于安全审计与故障排查。

API 速率限制(Rate Limiting)

v3.4 及以后

Argo Server 默认对每个 IP 每秒限流 1000 次请求,可通过 --api-rate-limit 调整。从源码看,该限制基于内存存储实现:memorystore.New 以 APIRateLimit 为令牌数、1s 为窗口(argoserver.go),并通过 gRPC 拦截器(grpcutil.RatelimitUnaryServerInterceptor / RatelimitStreamServerInterceptor)与 HTTP 中间件(httplimit,基于 IPKeyFunc 按客户端 IP 识别)双层生效(argoserver.go、argoserver.go)。

当请求被限流时,响应中会携带以下头部供客户端解析:

Header 含义
X-Rate-Limit-Limit 当前请求适用的速率上限
X-Rate-Limit-Remaining 当前限流窗口内剩余的可请求次数
X-Rate-Limit-Reset 限流重置的时间(UTC)
Retry-After 客户端应多久后重试(限流过期时间,UTC)

另外,源码中还提供了 IP_KEY_FUNC_HEADERS 环境变量,可指定以哪些请求头来识别客户端 IP(argoserver.go),在真实客户端 IP 无法直接获取(例如多层代理)时非常有用。

小结

Argo Server 是 Argo Workflows 面向用户侧的"门面":它既承载了 Web UI 与完整的管理 API,也是访问大型工作流卸载与工作流归档数据的必经组件。理解其托管/本地两种模式、--auth-mode、--base-href、--api-rate-limit 等关键启动选项,以及端口转发、LoadBalancer、Ingress 三种 UI 暴露方式,再结合文中涉及的安全建议与限流响应头,即可在生产集群中安全、稳定地对外提供 Argo Workflows 服务。如需进一步深入,可继续阅读仓库内的 server/apiserver/argoserver.go、cmd/argo/commands/server.go 及 manifests/base/argo-server/ 下的部署清单。

登录后查看全文
argo-workflows