使用 Helm 在 Kubernetes 上自托管部署 ZenML Pro 控制平面-迪斯科星球

使用 Helm 在 Kubernetes 上自托管部署 ZenML Pro 控制平面

【免费下载链接】zenmlZenML 🙏: One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenml

ZenML Pro 支持完全自托管的部署形态：控制平面、工作区服务器、数据库、存储与计算全部运行在你自己的 Kubernetes 集群与基础设施内部，实现零外部依赖与数据主权。本文以仓库中部署文档为主线，完整讲解从前置条件、Helm Values 配置、控制平面安装上线、超级用户引导，到工作区接入与 CLI 登录的全流程，并结合仓库内 Helm Chart 与源码给出参数背后的实现细节。

部署架构：一切组件都运行在你的基础设施中

自托管部署的核心特征在 Self-hosted Deployment Overview 中定义得很明确：所有组件、元数据与 ML 制品都留在你的基础设施边界之内，运行不需要任何互联网连接，适用于有数据驻留、合规或完全隔离网络要求的场景。

架构组件：按命名空间划分的职责

从部署文档的架构描述可以拆出如下四类运行单元：

命名空间 / 层	承载组件	职责
客户端访问层	浏览器访问的 ZenML UI 控制台；开发者笔记本或 CI 系统到工作区的连接	用户交互与 API 调用入口
`zenml-controlplane-namespace`	UI Pod（ZenML Pro UI，连接控制平面与所有工作区）；Control Plane Pod（API Server 与用户管理 / RBAC）	控制平面：组织、用户、RBAC、工作区协调
`zenml-workspace-namespace`	Workspace Server Pod（ZenML API Server）与 Workload Manager（管理流水线、Stack 与快照）	工作区：流水线元数据与执行管理
`zenml-runners-namespace`/`orchestrator-namespace`	按需创建的 Runner Pod（快照执行）、使用 Kubernetes orchestrator 时的 Orchestrator Pod	流水线实际执行

数据与存储层

MySQL 数据库（TCP 3306）：存储控制平面与工作区的元数据；
可选 Secrets 后端：如 AWS Secrets Manager 或 HashiCorp Vault，集中存放凭据；
制品存储（S3、GCS 或 Azure Blob）：保存模型、数据集与流水线制品；
容器镜像仓库（AWS ECR、Google Artifact Registry 或 Azure Container Registry）：存放流水线镜像。

与仓库 Helm Chart 的对应关系

仓库自带的开源 ZenML Helm Chart（Chart.yaml，当前版本0.96.3）是工作区服务器部署的基础。在 server-deployment.yaml 中可以看到 API Server 容器实际以uvicorn zenml.zen_server.zen_server_api:app启动，监听8080端口，并通过/health与/ready探针做存活与就绪检查——这也对应了控制平面部署后“等待所有 Pod 处于 Running 且健康”的验证步骤。

前置条件

在动手之前，应先阅读自托管部署通用前置条件，收集好制品与信息。针对 Kubernetes + Helm 部署，本指南列出的特定要求如下：

基础设施：

Kubernetes 集群（1.24+）

网络：

负载均衡器、网络网关或 Ingress 控制器等
内部 DNS 解析
由内部 CA 签发的 TLS 证书（或自签名证书）
集群组件之间的网络连通性

工具（在可访问互联网的机器上，用于初始安装）：

Helm（3.0+）

镜像仓库访问：先申请再拉取

ZenML Pro 控制平面的两个组件（zenml-pro-api与zenml-pro-dashboard）共用同一版本号（如0.13.0），镜像私有托管在 ZenML 的 GCP Artifact Registry 与 AWS ECR 仓库中，访问权限按申请授予（联系 cloud@zenml.io）：

GCP Artifact Registry：europe-west3-docker.pkg.dev/zenml-cloud/zenml-pro/zenml-pro-api:<version>、europe-west3-docker.pkg.dev/zenml-cloud/zenml-pro/zenml-pro-dashboard:<version>
AWS ECR：715803424590.dkr.ecr.eu-west-1.amazonaws.com/zenml-pro-api:<version>、715803424590.dkr.ecr.eu-west-1.amazonaws.com/zenml-pro-dashboard:<version>

认证方式有三种：AWS IAM Role（推荐给 AWS 工作负载，支持 EKS IRSA / ECS 任务执行角色 / EC2 实例配置角色）、GCP Service Account（推荐给 GCP 工作负载，支持 Workload Identity / Cloud Run / Compute Engine）、Docker 凭据（其他环境）。zenml-proHelm Chart 则公开托管于 ECR 的oci://public.ecr.aws/zenml/zenml-pro。

关于镜像 Tag 的版本同步

前置条件文档强调了一个容易踩坑的点：控制平面镜像 Tag 与 ZenML Pro Helm Chart 版本是同步的。若使用内部镜像仓库，重新打 Tag 时务必保留原版本号，以维持组件间兼容。

安装 ZenML Pro 控制平面

安装过程分为五个步骤：创建 Kubernetes Secrets、配置 Helm Values、用 Helm 部署、引导控制平面（创建超级用户）、部署并注册工作区。

Step 1：创建 Kubernetes Secrets

如果使用内部容器镜像仓库，需要先创建 Secret 以允许控制平面与工作区服务器拉取镜像：

# 为 ZenML Pro 创建命名空间 kubectl create namespace zenml-pro # 为内部仓库凭据创建 Secret（如需） kubectl -n zenml-pro create secret docker-registry image-pull-secret \ --docker-server=internal-registry.mycompany.com \ --docker-username=<your-username> \ --docker-password=<your-password>

该 Secret 会在下一步 Helm Values 的imagePullSecrets中被引用。在仓库的 server-deployment.yaml 中，imagePullSecrets会被直接渲染进 Pod 规格，因此集群节点从私有仓库拉取镜像时会自动带上这些凭据。

Step 2：配置控制平面的 Helm Values

以下是控制平面 Helm Chart 的基础配置。完整可配置项可查阅 ZenML Pro Helm Chart 参考（ArtifactHub 上的zenml-pro/zenml-pro）。

# 设置 imagePullSecrets 以认证到存放 ZenML Pro 容器镜像的仓库（见上一步） imagePullSecrets: - name: image-pull-secret # ZenML Pro 服务器相关选项。 zenml: image: api: # 改成你自己的容器仓库 repository: internal-registry.mycompany.com/zenml/zenml-pro-api # 或直接使用 GAR： # repository: europe-west3-docker.pkg.dev/zenml-cloud/zenml-pro/zenml-pro-api # 或直接使用 AWS ECR： # repository: 715803424590.dkr.ecr.eu-west-1.amazonaws.com/zenml-pro-api # 仅当需要覆盖默认 Tag 时使用；默认值等于 Helm Chart 的 appVersion。 # tag: <ZENML_PRO_VERSION> dashboard: repository: internal-registry.mycompany.com/zenml/zenml-pro-dashboard # repository: europe-west3-docker.pkg.dev/zenml-cloud/zenml-pro/zenml-pro-dashboard # repository: 715803424590.dkr.ecr.eu-west-1.amazonaws.com/zenml-pro-dashboard # tag: <ZENML_PRO_VERSION> # 控制平面 API 与 UI 可达的外部 URL。 # 应设置为与 Ingress 控制器、负载均衡器或任何网络网关关联的主机名。 serverURL: https://zenml-pro.internal.mycompany.com # 数据库配置。 database: # 连接外部 Postgres 或 MySQL 数据库的凭据。 external: # 外部数据库服务类型： # - postgres: 外部 Postgres 数据库 # - mysql: 外部 MySQL 数据库 type: mysql # 外部数据库服务主机 host: mysql.internal.mycompany.com # 连接数据库的用户名 username: zenml_pro_user # 连接数据库的密码 password: <secure-password> # 使用的数据库名。若不存在，首次运行时会自动创建。 # 注意：若数据库用户没有创建数据库的权限，需在安装 Helm Chart 前手动创建。 database: zenml_pro auth: sso: # 若使用外部 OIDC 身份提供商，启用 SSO 认证。 # 前置条件与配置细节见 SSO 指南。 enabled: true oidcConfigurationEndpoint: https://idp.example.com/.well-known/openid-configuration clientID: <your-oidc-client-id> clientSecret: <your-oidc-client-secret> password: # 若使用本地账户，启用密码认证。 # 部署完成后会创建一个 `admin` 账户并生成随机密码。 enabled: true # 自定义安装时创建的默认 admin 用户密码。 # 若不指定，则生成随机密码。 adminPassword: # Ingress 配置（若使用 Ingress 控制器）。 ingress: enabled: true # 使用与 serverURL 相同的主机名 host: zenml-pro.internal.mycompany.com

最少必需设置：

数据库凭据（zenml.database.external）
控制平面 API 与 UI 的可达 URL（zenml.serverURL）

可能相关的进阶设置：

配置容器仓库凭据（imagePullSecrets）
注入自定义 CA 证书（zenml.certificates）——当 ZenML Pro 服务的 TLS 证书由自定义 CA 签发时尤其重要
配置 HTTP 代理（zenml.proxy）
自定义镜像仓库位置（zenml.image.api与zenml.image.dashboard）
默认 admin 账户的用户名密码（zenml.auth.password）
SSO 认证设置（zenml.auth.sso）——前置条件与从密码认证迁移见 Single Sign-On (SSO) 指南
更多 Ingress 设置（zenml.ingress）
Pod 的 Kubernetes 资源配额（resources）
若为所有 ZenML Pro 服务规划了公共 DNS 前缀，可通过zenml.auth.authCookieDomain将 Dashboard 的 HTTP Cookie 域配置为该前缀（例如.my.domain而非zenml-pro.my-domain）

自定义 CA 证书的底层实现

文档特别强调zenml.certificates对于内部 CA 签名的场景至关重要。仓库的 server-deployment.yaml 展示了它的实现方式：当配置了customCAs或secretRefs时，Chart 会注入一个名为update-ca-certificates的 initContainer，将系统 CA 包与所有自定义证书合并追加到/updated-certs/ca-certificates.crt，再挂载进主容器。也就是说，自定义 CA 会在服务启动前被"烘焙"进容器的信任链中。

Step 3：使用 Helm 部署控制平面

使用远程 Helm Chart（可访问互联网时）：

helm install zenml-pro oci://public.ecr.aws/zenml/zenml-pro \ --namespace zenml-pro \ --create-namespace \ --values zenml-pro-values.yaml \ --version <ZENML_PRO_VERSION>

使用本地 Helm Chart（已提前下载 Chart 时）：

helm install zenml-pro ./zenml-pro-<ZENML_PRO_VERSION>.tgz \ --namespace zenml-pro \ --create-namespace \ --values zenml-pro-values.yaml

验证部署：

kubectl -n zenml-pro get pods kubectl -n zenml-pro get svc kubectl -n zenml-pro get ingress

等待所有 Pod 处于 Running 且健康状态。

Step 4：引导 ZenML Pro 控制平面（创建首个超级用户）

下一步是创建你的第一个超级用户账户。

什么是超级用户？超级用户是拥有额外权限的特殊账户，可以绕过 RBAC 限制，为整个 ZenML Pro 实例创建和管理其他用户账户、组织与工作区资源。超级用户权限之后可以授予其他用户，也可以在不需要时收回。

你将使用该账户登录 ZenML Pro UI 完成上线引导任务：

创建一个或多个组织。配置 SSO 后，组织的可信域名（通过 API）可以改变用户发现方式，以及部分邀请是否需要显式接受。
创建用户账户和/或邀请其他用户加入组织。
为用户分配角色与权限，或将用户分组为团队。
在组织中注册工作区。

创建初始超级用户的方式取决于你使用的是 SSO 认证还是密码认证。

方式一：使用 SSO 认证

如果启用了 SSO，直接访问 ZenML Pro UI，通过 SSO 登录流程向身份提供商完成认证即可。

使用 SSO 登录的第一个账户将被自动授予超级用户权限。

方式二：使用密码认证

如果只启用了密码认证，系统会保留一个 admin 账户用于创建第一个本地超级用户。如何访问该 admin 账户的说明会打印在 Helm Chart 部署后的输出中：

You may access the ZenML Pro server at: https://zenml-pro.my.domain Use the following credentials: Username: admin Password: fetch the password by running: kubectl get secret --namespace zenml-pro zenml-pro -o jsonpath="{.data.ZENML_CLOUD_ADMIN_PASSWORD}" | base64 --decode; echo

警告：admin 账户只应用于初始引导与涉及超级用户管理的应急运维操作（创建第一个超级用户、在需要时授予其他用户超级用户权限）。其他所有操作请使用普通用户账户。

创建和管理本地用户账户目前只能通过 ZenML Pro OpenAPI 接口或编程方式访问 ZenML Pro API 完成，ZenML Pro UI 暂不支持。

OpenAPI 接口方式：在浏览器中访问 ZenML Pro 服务器 URL 并追加/api/v1路径，例如https://zenml-pro.my.domain/api/v1，然后在 OpenAPI UI 中用 admin 用户名和密码认证。通过向/api/v1/users端点发起请求即可管理本地用户账户。

curl 方式：先获取 bearer token，再用它创建超级用户：

# 用 admin 凭据获取 bearer token curl -X POST https://zenml-pro.my.domain/api/v1/auth/login \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "username=admin&password=<admin-password>"

响应中包含access_token字段，用它创建新的超级用户账户：

# 创建新的超级用户账户 curl -X POST "https://zenml-pro.my.domain/api/v1/users?username=superuser&password=password&is_superuser=true" \ -H "Authorization: Bearer <access-token>"

Step 5：部署并注册工作区

控制平面引导完成后，即可部署并注册一个或多个工作区。工作区的部署与注册流程见在 Kubernetes 上部署工作区，其中需要用到自托管部署时使用的控制平面 URL：

ZenML Pro 控制平面 UI：https://zenml-pro.internal.mycompany.com
ZenML Pro 控制平面 API：https://zenml-pro.internal.mycompany.com/api/v1s

补充说明：工作区服务器构建在开源 ZenML 服务器之上，使用开源zenmlHelm Chart 部署，核心差异仅在于连接控制平面的server.pro.*配置（apiURL、dashboardURL、enrollmentKey、organizationID/Name、workspaceID/Name），且其数据库仅支持 MySQL。仓库的 values.yaml 中server.pro段即为此而设，pro.enabled: true时会覆盖zenml段中的部分默认配置。

从 ZenML CLI 访问工作区

要用 ZenML CLI 登录工作区，需要传入自定义的 ZenML Pro API URL：

zenml login --pro-api-url https://zenml-pro.internal.mycompany.com/api/v1

或者设置ZENML_PRO_API_URL环境变量：

export ZENML_PRO_API_URL=https://zenml-pro.internal.mycompany.com/api/v1 zenml login

这个机制在源码层面有明确对应：src/zenml/login/pro/constants.py定义了ZENML_PRO_API_URL环境变量，默认值为https://cloudapi.zenml.io（即 SaaS 场景）；当环境变量或--pro-api-url参数传入自托管地址时，cli/login.py 中的--pro-api-url选项就会覆盖默认值，把 CLI 指向你的自托管控制平面。

Day 2 运维

ZenML Pro 各组件的升级操作参见 Upgrades & Updates 指南。自托管场景下，升级通常以离线 Bundle 的形式提供：先接收新版本 Bundle（通常通过经批准的传输方式拉取 Docker 镜像），审阅发布说明与迁移指南，在预发布环境测试，备份当前数据库与配置状态，再用 Helm upgrade 命令或 IaC 工具应用更新，最后通过健康检查与测试验证功能并监控升级后的异常。

支持与更多资源

自托管部署可联系 ZenML 支持（cloud@zenml.io），并提供部署状态、配置细节与错误日志。可向 ZenML 申请：部署前架构咨询、离线支持包、更新 Bundle 与发布说明、安全文档（SBOM、漏洞报告）。

企业官网建设流程全解析