#安装 MLflow

在 Alauda AI 2.8.x 中，MLflow 由 Alauda AI 安装和管理。集群作用域的 default AmlCluster 中的 mlflow 组件默认值为 Unmanaged；将其设置为 Managed 后，Alauda AI 会自动安装 MLflow Operator，你无需手动从 OperatorHub 安装该 Operator。启用该组件只会安装 Operator；你仍然需要创建一个 MLflow 自定义资源来部署 tracking-server 堆栈，如 创建 MLflow tracking server 中所述。

#前提条件

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

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

• PostgreSQL 12 或更高版本数据库 可从集群访问，并包含一个名为 mlflow 的数据库用于 MLflow 元数据。请准备好主机、端口、用户名和密码，并在安装前创建数据库：

  CREATE DATABASE mlflow;

  生产环境请使用高可用 PostgreSQL 服务（参见 高可用性和存储）。

• 用于生产 artifact 存储的现有 S3 兼容 bucket，可位于 SeaweedFS、MinIO、Ceph RGW 或 AWS S3 中。operator 可以代理 artifact 访问，因此客户端无需 object-storage 凭据。pod 内文件系统默认值仅适用于 smoke test。

• 平台 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

在 Administrator 视图中：

1. 打开 Marketplace > OperatorHub。
2. 选择目标集群并打开 Alauda AI。
3. 打开 All Instances 选项卡，并编辑 default AmlCluster 实例。
4. 将 spec.components.mlflow.managementState 设置为 Managed。
5. 保存 AmlCluster 实例，并等待 MLflow Operator 就绪。

你也可以在 AmlCluster YAML 中应用该组件设置：

spec:
  components:
    mlflow:
      managementState: Managed

继续之前，请确认 operator 已就绪：

kubectl get amlcluster default

# 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

AmlCluster 应报告 Phase=Ready。启用该组件只会安装 MLflow Operator；只有在你按照下文创建 MLflow 自定义资源后，tracking server 才会被部署。

#创建 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

设置数据库连接和多租户字段，然后应用：

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
    # Recommended for production. The bucket and Secret must already exist.
    s3:
      enabled: true
      endpointUrl: https://object-storage.example.com
      bucket: mlflow
      prefix: production
      existingSecret: mlflow-s3-credentials
      accessKeyIdKey: AWS_ACCESS_KEY_ID
      secretAccessKeyKey: AWS_SECRET_ACCESS_KEY
      proxied: true

将其保存为 mlflow.yaml 并应用：

kubectl apply -f 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 连接、多租户 workspace 字段以及 S3 artifact 存储字段。
6. 点击 Create。

#验证

验证 tracking server 是否已在配置的命名空间（kubeflow）中完成 reconcile：

# 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 和可见的 workspaces 会反映你登录所使用的身份。

#高可用性和存储

• 数据库。 MLflow 会将所有 experiment/run/registry 元数据存储在你配置的外部 PostgreSQL 中。生产环境请使用高可用 PostgreSQL 服务；tracking server 本身在元数据方面是无状态的。
• Artifacts。 默认的 artifacts.defaultArtifactRoot: /mlflow/artifacts 是 tracking-server pod 本地的 emptyDir。它不具备持久性，外部客户端也无法可靠地使用 server 本地路径。从 v3.13.0 开始，请在用户记录 artifact 或注册模型之前，为生产环境启用 artifacts.s3。在默认的 proxied: true 下，tracking server 会存储 S3 凭据，客户端则通过经过身份验证的 MLflow endpoint 上传。
• Replicas。 默认部署为单副本。除非你的 release notes 另有说明，否则这不是多副本高可用部署。

在应用 MLflow 资源之前，请先在 tracking-server namespace 中创建所引用的 credentials Secret：

kubectl -n kubeflow create secret generic mlflow-s3-credentials \
  --from-literal=AWS_ACCESS_KEY_ID='<access-key>' \
  --from-literal=AWS_SECRET_ACCESS_KEY='<secret-key>'

bucket 必须已存在。对于 AWS S3，请将 endpointUrl 留空。对于 S3 兼容服务，请将其设置为服务 endpoint。必要时，你还可以在 artifacts.s3 下设置 region、ignoreTls 和 prefix。

#Bearer-token 客户端

从 v3.13.0 开始，operator 默认启用 spec.auth.oauth.skipJwtBearerTokens: true，允许 MLflow Python SDK 通过 MLFLOW_TRACKING_TOKEN 使用 Dex id token 进行身份验证。如果现有安装覆盖了 OAuth 设置，请确认该字段仍保持启用。请参见 SDK 指南中的 验证 token 方法。浏览器 session-cookie 方法也仍然可用。

#从 v3.10.x 升级到 v3.13.0

stable OLM channel 支持此升级。在批准之前，请先备份 PostgreSQL 后端数据库和 S3 artifact bucket。backend-store schema 迁移会在 tracking server 启动时自动运行。

升级后，请保留 spec.auth.kubernetes.authorizationMode: user_identity_token 和 spec.auth.oauth.skipJwtBearerTokens: true。这些默认值会保留本文档所述的 Dex bearer-token 流程。

#故障排查

• 如果 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 连通性、mlflow 数据库是否存在，以及 spec.pg* 中的凭据是否正确。
• 如果 artifact 上传或模型注册失败，请验证 artifacts.s3.enabled 是否为 true、bucket 是否存在，以及所引用的 credentials Secret 和 key 名称是否正确。
• 如果某个 workspace 不可见，请验证其 namespace 是否与已配置的 workspaceLabelSelector 匹配。
• 如果请求被拒绝（403 PERMISSION_DENIED），请检查 workspace namespace 中用户的 Kubernetes RoleBinding——参见 MLflow Workspaces and Access Control。