安装

MLflow 作为 OLM Operator(即 MLflow Operator)交付,并从平台 OperatorHub 安装。安装 tracking server 是一个两步流程:先安装 operator,然后创建一个 MLflow 自定义资源,用于协调 tracking-server stack。

前提条件

  • 目标集群上已安装 Alauda AI。operator 及其镜像同时提供 linux/amd64 和 linux/arm64 版本。

  • 目标集群上可用 Operator Lifecycle Manager (OLM)(由平台提供)。

  • 集群可访问的 PostgreSQL database,其中包含一个名为 mlflow 的 database,用于存储 MLflow metadata。请准备好 host、port、username 和 password,并在安装前创建 database:

    CREATE DATABASE mlflow;

    生产环境请使用高可用 PostgreSQL service(参见 高可用性和存储)。

  • 平台 OAuth / OIDC provider(由 Alauda AI 提供)——tracking server 前面的 OAuth proxy 会使用它进行单点登录。

  • 对于多租户场景,默认 workspace namespace 在 tracking server 首次启动之前必须已经存在,并带有标签 mlflow-enabled=true。 否则 server 会进入 crash-loop,并提示 Workspace '<name>' not found in the Kubernetes cluster。

    kubectl create namespace finetune
    kubectl label namespace finetune mlflow-enabled=true

上传 Operator

从 Customer Portal / Marketplace 下载 MLflow Operator bundle(例如 mlflow.ALL.xxxx.tgz),然后使用 violet 命令行工具将其发布到平台 repository:

violet push \
  --platform-address=<platform-access-address> \
  --platform-username=<platform-admin> \
  --platform-password=<platform-admin-password> \
  mlflow.ALL.xxxx.tgz
INFO

operator bundle 会在 CSV 的 relatedImages 中记录所有运行时镜像(operator、MLflow tracking server,以及 oauth2-proxy),因此 violet 发布会将它们重新定位到平台 registry。这样即使在离线集群中,也无需访问 build-harbor.alauda.cn / docker.io,即可安装该 operator。

安装 Operator

在 Administrator 视图中:

  1. 单击 Marketplace / OperatorHub。
  2. 在控制台顶部的 Cluster 下拉列表中,选择目标集群。
  3. 搜索并选择 MLflow Operator,然后单击 Install。
  4. 保持 Channel 不变(stable)。
  5. 确认 Version 与要安装的版本一致(例如 v3.10.2)。
  6. 保持 Installation Location 不变——其默认值为 mlflow-operator namespace。
  7. 选择 Upgrade Strategy(生产环境建议使用 Manual)。
  8. 单击 Install。

继续之前,请确认 operator 已就绪:

# the CSV reports Succeeded
kubectl get csv -n mlflow-operator | grep mlflow-operator

# the operator controller-manager pod is Running
kubectl get pods -n mlflow-operator

创建 MLflow tracking server

在创建 MLflow 自定义资源(mlflow.alauda.io/v1alpha1)之前,operator 不会执行任何操作。你可以通过两种方式创建它:

  • kubectl —— 应用一个 MLflow manifest。
  • Alauda Console UI —— 从 Administrator → Marketplace → OperatorHub → MLflow Operator → All instances → Create。

两种方式创建的是同一个资源;请根据你的工作流选择合适的方法。

方法 A — 使用 kubectl

设置 database connection 和多租户字段,然后应用:

apiVersion: mlflow.alauda.io/v1alpha1
kind: MLflow
metadata:
  name: mlflow
spec:
  # Namespace the tracking server is deployed into (chart-mandated: kubeflow).
  namespace: kubeflow

  # External PostgreSQL for MLflow metadata — the `mlflow` database must already exist.
  pgHost: postgresql.database.svc
  pgPort: 5432
  pgUsername: mlflow
  pgPassword: <db-password>

  # Multi-tenancy: map Kubernetes namespaces to MLflow workspaces.
  multitenancy:
    enabled: true
    defaultWorkspace: finetune                 # must exist and be labelled before first boot
    workspaceLabelSelector: mlflow-enabled=true

  # Run-artifact location (see High availability and storage below).
  artifacts:
    defaultArtifactRoot: /mlflow/artifacts

保存为 mlflow.yaml 后应用:

kubectl apply -f mlflow.yaml
INFO

在当前版本中,operator 会从 kube-public/global-info ConfigMap 中解析集群相关值——ingress/ALB 名称、cluster name 和 image registry,因此通常不需要设置 spec.global 和 spec.platformAddr。auth 设置(oauth2-proxy 配置)也有合理默认值。控制台中的 Create 表单会预填一个完整示例(operator 的 alm-examples),你可以直接编辑;完整字段集记录在 operator 的 config/samples/mlflow_v1alpha1_mlflow.yaml 中。

方法 B — 使用 Alauda Console UI

  1. 在 Administrator 视图中,进入 Marketplace → OperatorHub。
  2. 从顶部的 Cluster 下拉列表中选择目标集群。
  3. 打开已安装的 MLflow Operator。
  4. 切换到 All instances 选项卡并单击 Create(如有提示,请选择 MLflow)。
  5. 填写表单,或切换到 YAML 视图并粘贴方法 A 中的 manifest。设置 PostgreSQL connection,并且在多租户场景下,设置 defaultWorkspace 和 label selector。
  6. 单击 Create。

验证

验证 tracking server 是否已在配置的 namespace(kubeflow)中协调完成:

# the operand exists
kubectl get mlflow

# the tracking-server Deployment is Available (two containers: the server + oauth2-proxy)
kubectl -n kubeflow get deploy mlflow-tracking-server

# its pod is Running
kubectl -n kubeflow get pods -l app.kubernetes.io/name=mlflow-tracking-server

然后打开 Alauda AI → Tools → MLFlow。run owner 和可见 workspace 会反映你当前登录的身份。

高可用性和存储

  • Database。 MLflow 会将所有 experiment/run/registry metadata 存储在你配置的外部 PostgreSQL 中。生产环境请使用高可用 PostgreSQL service;tracking server 本身在 metadata 方面是无状态的。
  • Artifacts。 默认的 artifacts.defaultArtifactRoot: /mlflow/artifacts 仅本地于 tracking-server pod(一个 emptyDir),仅适用于开发和测试——它不是持久化的,而且上传大型 artifact 的客户端可能会遇到 pod 磁盘限制。生产环境中,请在用户存储 experiment artifacts 之前,将 artifact root 配置为兼容 S3 的 object store。
  • Replicas。 默认部署为单副本。除非你的 release notes 明确说明,否则它不是多副本高可用部署。

启用 bearer-token 客户端(可选)

默认情况下,OAuth proxy 接受浏览器 session cookie。若要让 MLflow Python SDK 使用 Dex id token(MLFLOW_TRACKING_TOKEN)进行认证,必须将 proxy 配置为接受 JWT bearer tokens(--skip-jwt-bearer-tokens / OAUTH2_PROXY_SKIP_JWT_BEARER_TOKENS=true)。请参见 SDK 指南中的 Platform setup for the token method。cookie 方法无需任何更改。

故障排查

  • 如果 MLFlow Tools 菜单项缺失,请确认 tracking-server namespace 中存在 aml-mlflow-menu-config ConfigMap,并且其标签为 aml.cpaas.io/centralMenuItem: "true"。
  • 如果 server 无法启动,并且 pod 日志显示 Workspace '<name>' not found,说明 defaultWorkspace namespace 不存在或未标记为 mlflow-enabled=true。请创建并添加该标签,然后重启 pod。
  • 如果 server 因其他原因无法启动,请验证 PostgreSQL connectivity、mlflow database 是否存在,以及 spec.pg* 中的凭据是否正确。
  • 如果某个 workspace 不可见,请验证其 namespace 是否与配置的 workspaceLabelSelector 匹配。
  • 如果请求被拒绝(403 PERMISSION_DENIED),请检查 workspace namespace 中用户的 Kubernetes RoleBinding——请参见 工作区和访问控制。