Argo Workflows 的 Argo Server:架构、部署模式与安全配置全指南
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/ 下的部署清单。