#安装 Kubeflow Operators

本文介绍如何在 Alauda AI 2.3 及更高版本中部署与 Kubeflow 相关的 operator。

从 v26.3.0（Alauda AI v2.3）开始，Kubeflow 以 OLM Helm Operators 的形式发布，而不是早期的 Cluster Plugin 形态。安装通过 ACP OperatorHub 完成，而不是通过 Cluster Plugins。这些 operator 封装了上游 kubeflow/manifests 26.03 charts。

支持的 operator：

• kfbase-operator：Kubeflow 基础组件，包括身份验证和授权、中心监控面板、Notebooks、PVC Viewer、TensorBoards、Volumes、Model Registry UI、KServe Endpoints UI，以及 Model Catalog API service。负责管理 KubeflowBase CR。架构：amd64、arm64。
• kfp-operator：Kubeflow Pipelines（KFP runtime 2.16.0）。负责管理 KubeflowPipelines CR。架构：仅 amd64（根据 Alauda AI v2.3 支持的配置，Kubeflow Pipelines 仅支持 x86_64）。
• kubeflow-trainer-operator：Kubeflow Trainer v2（controller-manager 2.1.0 + JobSet 0.10.1）。负责管理 KubeflowTrainer CR。架构：amd64、arm64。替代已弃用的 kftraining 插件。
• model-registry-operator：Kubeflow Model Registry operator（形态不变）。

注意： kftraining Cluster Plugin（Kubeflow Training Operator v1）在早期版本中已弃用，并已在 v26.3.0 中退役。请改用 kubeflow-trainer-operator（Trainer v2）。

#环境准备

开始之前，请确保满足以下前提条件：

1. ACP 环境可用且正在运行。
2. Alauda AI 已部署。v26.3.0 operator 集需要 Alauda AI 2.3 或更高版本。
3. 已安装 Alauda Build of KServe。
4. 业务集群中已部署 ASM，Kubeflow 将运行在该集群中。如果尚未安装 ASM，请先部署后再继续。ASM v1 已弃用。请尽可能使用 ASM v2。
5. LeaderWorkerSet 已安装并就绪。LWS 通常由 Alauda AI 通过 default AmlCluster 中的 lws 组件进行管理；参见安装 Alauda AI。仅当你计划部署 kubeflow-trainer-operator 时才需要它。
6. 已按照下文配置 oauth2-proxy 插件。

#配置 Dex 重定向

注意： 在安装 kfbase-operator 并创建其 KubeflowBase CR 之前，请先配置用于 Dex 重定向的平台访问 URL。此步骤可能会更新平台 CA 证书。如果你在配置 oauth2-proxy 后证书发生变化，oauth2-proxy 配置可能会失败。

在 管理员 > System Settings > Platform Parameters 中，单击 Platform Access URLs 旁边的 Edit，并添加格式为 https://<your-kubeflow-domain> 的重定向 URL，例如 https://kubeflow.example.com。

• <your-kubeflow-domain> 必须与 KubeflowBase CR 中的 spec.global.kubeflowHost 一致。

#配置 oauth2-proxy 插件

获取平台 Dex CA 证书，供后续在 Global 集群中使用：

crt=$(kubectl get secret -n cpaas-system dex.tls -o jsonpath='{.data.tls\.crt}')
echo -n $crt | base64 -d

#配置 ASM v1（已弃用）

在 global 集群中，或在 ACP Platform Management > Resource Management 中，更新 ServiceMesh 资源，并在 spec 下添加以下内容。

注意： 如果已经配置了 spec.values.pilot.jwksResolverExtraRootCA，则只更新 spec.meshConfig.extensionProviders。添加新条目时不要删除现有条目。

spec:
  overlays:
    - kind: IstioOperator
      patches:
        - path: spec.values.pilot.env.PILOT_JWT_PUB_KEY_REFRESH_INTERVAL
          value: 1m
        - path: spec.values.pilot.jwksResolverExtraRootCA
          value: |
            -----BEGIN CERTIFICATE-----
            <YOUR_DEX_CA_CERTIFICATE_BASE64_HERE>
            -----END CERTIFICATE-----
        - path: spec.meshConfig.extensionProviders
          value:
            - envoyExtAuthzHttp:
                headersToDownstreamOnDeny:
                  - content-type
                  - set-cookie
                headersToUpstreamOnAllow:
                  - authorization
                  - path
                  - x-auth-request-user
                  - x-auth-request-email
                  - x-auth-request-access-token
                includeAdditionalHeadersInCheck:
                  X-Auth-Request-Redirect: http://%REQ(Host)%%REQ(:PATH)%
                includeRequestHeadersInCheck:
                  - authorization
                  - cookie
                  - accept
                port: 80
                service: oauth2-proxy.kubeflow-oauth2-proxy.svc.cluster.local
              name: oauth2-proxy-kubeflow

#配置 ASM v2

注意： 如果仍然存在任何 ASM v1 webhooks，请先将其删除。否则 Kubeflow 身份验证可能会失败。

kubectl delete validatingwebhookconfigurations istiod-default-validator
kubectl delete mutatingwebhookconfigurations istio-sidecar-injector-1-22
kubectl delete mutatingwebhookconfigurations istio-revision-tag-default

在 ACP 中，进入 管理员 > MarketPlace > OperatorHub，找到 Alauda Service Mesh v2，打开 All Instances 选项卡，定位类型为 Istio 的实例，例如 default，单击 Update，并在 spec 下添加以下内容：

spec:
  values:
    pilot:
      env:
        PILOT_JWT_PUB_KEY_REFRESH_INTERVAL: 1m
      jwksResolverExtraRootCA: |
        -----BEGIN CERTIFICATE-----
        <YOUR_DEX_CA_CERTIFICATE_BASE64_HERE>
        -----END CERTIFICATE-----
    meshConfig:
      extensionProviders:
        - envoyExtAuthzHttp:
            headersToDownstreamOnDeny:
              - content-type
              - set-cookie
            headersToUpstreamOnAllow:
              - authorization
              - path
              - x-auth-request-user
              - x-auth-request-email
              - x-auth-request-access-token
            includeAdditionalHeadersInCheck:
              X-Auth-Request-Redirect: http://%REQ(Host)%%REQ(:PATH)%
            includeRequestHeadersInCheck:
              - authorization
              - cookie
              - accept
            port: 80
            service: oauth2-proxy.kubeflow-oauth2-proxy.svc.cluster.local
          name: oauth2-proxy-kubeflow

#组件上架

下载以下 operator 的 bundle 软件包，然后按照上架软件包进行上传。这些 bundle 会将 operator 注册到 ACP OperatorHub。

• kfbase-operator：Kubeflow 基础功能（负责管理 KubeflowBase CR）。
• kfp-operator：Kubeflow Pipelines（负责管理 KubeflowPipelines CR）。仅支持 amd64。
• kubeflow-trainer-operator：Kubeflow Trainer v2（负责管理 KubeflowTrainer CR）。替代已弃用的 kftraining。
• model-registry-operator：Kubeflow Model Registry operator。

#部署步骤

#1. 部署 kfbase-operator（Kubeflow Base）

在 管理员 > MarketPlace > OperatorHub 中找到 kfbase-operator，然后单击 Install。接着打开 All Instances 选项卡，并创建一个 KubeflowBase CR，将 spec.global.kubeflowHost 设置为你的 Kubeflow 域名。等待部署完成。

部署完成后：

• 在 管理员 > System Settings > Platform Parameters 中，确认 Platform Access URLs 包含格式为 https://<your-kubeflow-domain> 的地址，其中 <your-kubeflow-domain> 与 KubeflowBase CR 中的 spec.global.kubeflowHost 一致。
• 配置 DNS 解析，或添加本地 hosts 条目，使 <your-kubeflow-domain> 解析到 kubectl -n istio-system get gateway kubeflow-external-gateway 分配的 IP 地址。

部署完成后，Kubeflow 入口会出现在 Alauda AI 的 Tools 下。

有关升级相关操作，请参见升级 Kubeflow Operators。

#2. 创建 Kubeflow 用户命名空间并绑定用户

在用户首次登录 Kubeflow 之前，需要先将 ACP 用户绑定到某个命名空间。以下示例将创建命名空间 kubeflow-admin-cpaas-io，并将 admin@cpaas.io 设为所有者。

注意： 如果在 Alauda AI 部署期间已经创建了该 Profile 资源，则可以跳过此步骤。

注意： 在创建 Notebook 实例及类似工作负载之前，你可能需要降低用户命名空间的 Pod Security Admission 级别。

apiVersion: kubeflow.org/v1beta1
kind: Profile
metadata:
  name: kubeflow-admin-cpaas-io
spec:
  owner:
    kind: User
    name: "admin@cpaas.io"

#3. 将用户绑定到现有命名空间

如果 Alauda AI 已经部署，且命名空间 kubeflow-admin-cpaas-io 已存在，那么 Profile 也可能已经存在。如果该命名空间仍未出现在 Kubeflow 中，请创建以下资源，将该账户绑定到该命名空间：

apiVersion: v1
kind: ServiceAccount
metadata:
  name: default-editor
  namespace: kubeflow-admin-cpaas-io
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: default-editor
  namespace: kubeflow-admin-cpaas-io
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: kubeflow-edit
subjects:
  - kind: ServiceAccount
    name: default-editor
    namespace: kubeflow-admin-cpaas-io
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: user-admin-cpaas-io-clusterrole-admin
  namespace: kubeflow-admin-cpaas-io
  annotations:
    role: admin
    user: "admin@cpaas.io"
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: kubeflow-admin
subjects:
  - apiGroup: rbac.authorization.k8s.io
    kind: User
    name: "admin@cpaas.io"
---
apiVersion: security.istio.io/v1beta1
kind: AuthorizationPolicy
metadata:
  name: user-admin-cpaas-io-clusterrole-admin
  namespace: kubeflow-admin-cpaas-io
  annotations:
    role: admin
    user: "admin@cpaas.io"
spec:
  rules:
    - from:
        - source:
            ## for more information see the KFAM code:
            ## https://github.com/kubeflow/kubeflow/blob/v1.8.0/components/access-management/kfam/bindings.go#L79-L110
            principals:
              ## required for Kubeflow notebooks
              ## TEMPLATE: "cluster.local/ns/<ISTIO_GATEWAY_NAMESPACE>/sa/<ISTIO_GATEWAY_SERVICE_ACCOUNT>"
              - "cluster.local/ns/istio-system/sa/istio-ingressgateway-service-account"

              ## required for Kubeflow pipelines
              ## TEMPLATE: "cluster.local/ns/<KUBEFLOW_NAMESPACE>/sa/<KFP_UI_SERVICE_ACCOUNT>"
              - "cluster.local/ns/kubeflow/sa/ml-pipeline-ui"
      when:
        - key: request.headers[kubeflow-userid]
          values:
            - "admin@cpaas.io"

#4. 部署 kfp-operator（Kubeflow Pipelines）

在 管理员 > MarketPlace > OperatorHub 中找到 kfp-operator，然后单击 Install。接着在 operator 实例命名空间中创建一个 KubeflowPipelines CR。待 CR 完成调谐后，KFP runtime 组件将被部署，且与 pipeline 相关的功能将在 Kubeflow UI 中可用。

注意： kfp-operator 仅支持 amd64。请勿在仅支持 arm64 的集群上安装。

注意： 只有在 KubeflowPipelines 完成调谐后，Kubeflow UI 中才会显示 pipeline 相关功能。

#5. 部署 Kubeflow Model Registry

在 管理员 > MarketPlace > OperatorHub 中找到 Model Registry Operator，然后单击 Install。

安装 operator 后，打开 All Instances 选项卡，并在用户的命名空间中创建一个 ModelRegistry 实例。

注意： 请在已经绑定到 Kubeflow Profile 的命名空间中创建该实例。否则不会显示 Model Registry UI。

创建实例时，请按需配置以下字段：

• 名称：Model Registry 实例的名称。
• 命名空间：实例运行所在的命名空间。该命名空间必须已绑定到 Kubeflow Profile。
• MySQL Storage Class：用于 Model Registry 元数据的存储类，例如 standard。
• MySQL Storage Size：元数据数据库的存储大小。默认值为 10Gi。
• DisplayName：Model Registry 实例的显示名称。
• Description：实例的简短描述。

注意： 实例启动后，请刷新 Kubeflow 左侧导航中的 Model Registry 入口，以查看新实例。在创建第一个实例之前，Model Registry 页面为空。

注意： Model Registry 实例会限制来自其他命名空间的网络请求。若要允许其他命名空间访问，请编辑该实例的 authorizationpolicy，例如执行 kubectl -n <your-namespace> edit authorizationpolicy <model-registry-name>，并根据 Istio 文档更新策略。

注意： 你可以在不同的命名空间中部署多个 Model Registry 实例。每个实例都是独立的。

#6. 部署 kubeflow-trainer-operator（Kubeflow Trainer v2）

注意： 如果仍然安装着已弃用的 kftraining Cluster Plugin（来自 v26.3.0 之前的集群），请先卸载它，然后再安装 kubeflow-trainer-operator。

注意： LeaderWorkerSet 是 kubeflow-trainer-operator 的依赖项。在部署 kubeflow-trainer-operator 之前，请通过 default AmlCluster 中的 lws 组件确认 LWS 已启用并就绪；参见安装 Alauda AI。

注意： kubeflow-trainer-operator 的 v26.3.0 版本与上游 kubeflow/manifests 26.03 对齐，并随附 Trainer v2.1.0 + JobSet v0.10.1。对于某些 OLM CatalogSource 已经声明更高 trainer 版本（>=2.2.0）的集群，请使用 installPlanApproval: Manual 和 startingCSV: kubeflow-trainer-operator.v2.1.0 进行安装，以防止 OLM 自动升级并超过 26.03 的版本锁定。

在 管理员 > MarketPlace > OperatorHub 中找到 kubeflow-trainer-operator，单击 Install，如果需要锁定版本，请选择 Manual install-plan approval，然后打开 All Instances 选项卡，并创建一个启用了 JobSet 的 KubeflowTrainer CR。