Kubeflow Manifests

目录

<!-- toc -->

• Kubeflow平台概述
• Kubeflow组件版本
• 安装
  • 前提条件
  • 单命令安装
  • 安装单个组件
  • 连接到Kubeflow集群
  • 更改默认用户密码
• 升级和扩展
• 发布流程
• CVE扫描
• 常见问题

<!-- tocstop -->

Kubeflow平台概述

本仓库由Manifests工作组维护。如果您是贡献者，正在编写或编辑软件包，请参阅最佳实践。您可以加入CNCF Slack并通过Kubeflow社区网站参加我们的会议。我们在CNCF Slack上的频道是#kubeflow-platform。您还可以在那里找到我们的双周会议，包括可评论的议程。

Kubeflow Manifests仓库主要分为三个目录，包含以下安装清单：

目录	用途
apps	Kubeflow官方组件，由各Kubeflow工作组维护
common	通用服务，由Manifests工作组维护
contrib	第三方贡献的应用（如Ray、Kserve），由外部维护，不属于Kubeflow工作组

所有组件都可以使用kustomize部署。您可以选择部署整个Kubeflow平台或单个组件。

Kubeflow组件版本

Kubeflow版本：master

本仓库定期从各自的上游仓库同步所有官方Kubeflow组件。以下矩阵显示了我们为每个组件包含的git版本：

组件	本地清单路径	上游修订版本
Training Operator	apps/training-operator/upstream	v1.8.0
Notebook Controller	apps/jupyter/notebook-controller/upstream	v1.9.0
PVC Viewer Controller	apps/pvcviewer-roller/upstream	v1.9.0
Tensorboard Controller	apps/tensorboard/tensorboard-controller/upstream	v1.9.0
Central Dashboard	apps/centraldashboard/upstream	v1.9.0
Profiles + KFAM	apps/profiles/upstream	v1.9.0
PodDefaults Webhook	apps/admission-webhook/upstream	v1.9.0
Jupyter Web App	apps/jupyter/jupyter-web-app/upstream	v1.9.0
Tensorboards Web App	apps/tensorboard/tensorboards-web-app/upstream	v1.9.0
Volumes Web App	apps/volumes-web-app/upstream	v1.9.0
Katib	apps/katib/upstream	v0.17.0
KServe	contrib/kserve/kserve	0.13.0
KServe Models Web App	contrib/kserve/models-web-app	0.13.0
Kubeflow Pipelines	apps/pipeline/upstream	2.2.0
Kubeflow Tekton Pipelines	apps/kfp-tekton/upstream	2.0.5
Kubeflow Model Registry	apps/model-registry/upstream	v0.2.1-alpha

以下是Kubeflow不同项目中使用的通用组件版本矩阵：

组件	本地清单路径	上游修订版本
Istio	common/istio-1-22	1.22.1
Knative	common/knative/knative-serving <br /> common/knative/knative-eventing	v1.12.4 <br /> v1.12.6
Cert Manager	common/cert-manager	1.14.5

安装

这是从头开始安装的说明。有关原地升级指南，请跳转至升级和扩展部分。

Manifests工作组提供了两种使用kustomize安装Kubeflow官方组件和通用服务的选项。目的是帮助终端用户轻松安装，并帮助发行版所有者从经过测试的起点构建他们的定制发行版：

1. 使用单个命令安装apps和common下的所有组件
2. 使用多个命令为apps和common安装单个组件

选项1针对终端用户的易部署性。 选项2针对定制性和选择单个组件的能力。

example目录包含了单命令安装的kustomization示例，可以直接运行。 ⚠️ 在两种选项中，我们都使用默认的电子邮箱（user@example.com）和密码（12341234）。对于任何生产环境的Kubeflow部署，您应该按照相关章节更改默认密码。

先决条件

• 这是针对Kubernetes 1.29+版本的主分支
• 关于每个版本对应的具体Kubernetes版本，请查阅发布说明
• 可以使用我们本地的Kind（将在下面安装）或您自己的Kubernetes集群，并配有默认的StorageClass
• Kustomize 5.2.1+版本
• 与您的Kubernetes集群兼容版本的Kubectl

---

注意

kubectl apply命令可能在第一次尝试时失败。这是由于Kubernetes和kubectl的工作方式固有的（例如，必须在CRD准备就绪后才能创建CR）。解决方法是简单地重复执行该命令直到成功。对于单行命令，我们已经包含了一个bash单行脚本来重试该命令。

---

使用单个命令安装

先决条件

• 建议32 GB RAM
• 建议16个CPU核心
• kind
• docker
• Linux内核子系统更改以支持多个pod
  • sudo sysctl fs.inotify.max_user_instances=2280
  • sudo sysctl fs.inotify.max_user_watches=1255360

创建kind集群

cat <<EOF | kind create cluster --name=kubeflow --config=-
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  image: kindest/node:v1.29.4
  kubeadmConfigPatches:
  - |
    kind: ClusterConfiguration
    apiServer:
      extraArgs:
        "service-account-issuer": "kubernetes.default.svc"
        "service-account-signing-key-file": "/etc/kubernetes/pki/sa.key"
EOF

保存kubeconfig

kind get kubeconfig --name kubeflow > /tmp/kubeflow-config
export KUBECONFIG=/tmp/kubeflow-config

基于现有凭证创建Secret以拉取镜像

docker login

kubectl create secret generic regcred \
    --from-file=.dockerconfigjson=/home/to/.docker/config.json \
    --type=kubernetes.io/dockerconfigjson

您可以使用以下命令安装所有Kubeflow官方组件（位于apps下）和所有通用服务（位于common下）：

while ! kustomize build example | kubectl apply -f -; do echo "重试应用资源"; sleep 20; done

一旦所有内容都成功安装，您可以登录到您的集群来访问Kubeflow中央仪表板。

恭喜！您现在可以开始使用Kubeflow进行实验和运行端到端的机器学习工作流程了。

安装单个组件

在本节中，我们将使用kubectl和kustomize分别安装每个Kubeflow官方组件（在apps下）和每个通用服务（在common下）。

如果执行以下所有命令，结果将与上述单命令安装部分相同。本节的目的是：

• 提供每个组件的描述及其安装方式的见解。
• 使用户或发行版所有者能够只选择他们需要的组件。

---

故障排除说明

在应用不同组件的kustomization时，我们遇到过类似以下的错误：

error: resource mapping not found for name: "<RESOURCE_NAME>" namespace: "<SOME_NAMESPACE>" from "STDIN": no matches for kind "<CRD_NAME>" in version "<CRD_FULL_NAME>"
ensure CRDs are installed first

这是因为kustomization同时应用了CRD和CR，而CRD尚未变为Established状态。您可以在https://github.com/kubernetes/kubectl/issues/1117和https://github.com/helm/helm/issues/4925中了解更多信息。

如果遇到此错误，我们建议重新应用该组件的kustomization。

---

cert-manager

许多Kubeflow组件使用cert-manager为准入webhook提供证书。

安装cert-manager：

kustomize build common/cert-manager/cert-manager/base | kubectl apply -f -
echo "等待cert-manager准备就绪 ..."
kubectl wait --for=condition=ready pod -l 'app in (cert-manager,webhook)' --timeout=180s -n cert-manager
kubectl wait --for=jsonpath='{.subsets[0].addresses[0].targetRef.kind}'=Pod endpoints -l 'app in (cert-manager,webhook)' --timeout=180s -n cert-manager

如果您遇到以下错误：

Error from server (InternalError): error when creating "STDIN": Internal error occurred: failed calling webhook "webhook.cert-manager.io": failed to call webhook: Post "https://cert-manager-webhook.cert-manager.svc:443/mutate?timeout=10s": dial tcp 10.96.202.64:443: connect: connection refused

这是因为webhook尚未准备好接收请求。等待几秒钟后重试应用清单。

更多故障排除信息，请查看https://cert-manager.io/docs/troubleshooting/webhook/

Istio

大多数Kubeflow组件使用Istio来保护其流量、执行网络授权和实施路由策略。

安装Istio：

echo "安装配置了外部授权的Istio..."
cd common/istio-1-22
kustomize build common/istio-1-22/istio-crds/base | kubectl apply -f -
kustomize build common/istio-1-22/istio-namespace/base | kubectl apply -f -
kustomize build common/istio-1-22/istio-install/overlays/oauth2-proxy | kubectl apply -f -

echo "等待所有Istio Pod变为就绪状态..."
kubectl wait --for=condition=Ready pods --all -n istio-system --timeout 300s

Oauth2-proxy

oauth2-proxy扩展了Istio Ingress-Gateway的功能，使其能够作为OIDC客户端：

echo "安装oauth2-proxy..."
kustomize build common/oauth2-proxy/overlays/m2m-self-signed/ | kubectl apply -f -
kubectl wait --for=condition=ready pod -l 'app.kubernetes.io/name=oauth2-proxy' --timeout=180s -n oauth2-proxy

它支持用户会话以及适当的基于令牌的机器到机器认证。

Dex

Dex是一个具有多种认证后端的OpenID Connect Identity (OIDC)系统。在这个默认安装中，它包含一个静态用户，其电子邮箱为user@example.com。默认情况下，用户的密码是12341234。对于任何生产环境的Kubeflow部署，您应该按照相关章节更改默认密码。

安装Dex：

kustomize build common/dex/overlays/oauth2-proxy | kubectl apply -f -

Knative

KServe官方Kubeflow组件使用Knative。

安装Knative Serving：

kustomize build common/knative/knative-serving/overlays/gateways | kubectl apply -f -
kustomize build common/istio-1-22/cluster-local-gateway/base | kubectl apply -f -

您也可以选择安装 Knative Eventing，它可用于推理请求日志记录：

kustomize build common/knative/knative-eventing/base | kubectl apply -f -

Kubeflow 命名空间

创建 Kubeflow 组件所在的命名空间。该命名空间名为 kubeflow。

安装 kubeflow 命名空间：

kustomize build common/kubeflow-namespace/base | kubectl apply -f -

Kubeflow 角色

创建 Kubeflow ClusterRoles：kubeflow-view、kubeflow-edit 和 kubeflow-admin。Kubeflow 组件将权限聚合到这些 ClusterRoles。

安装 kubeflow 角色：

kustomize build common/kubeflow-roles/base | kubectl apply -f -

Kubeflow Pipelines

安装 多用户 Kubeflow Pipelines 官方 Kubeflow 组件：

kustomize build apps/pipeline/upstream/env/cert-manager/platform-agnostic-multi-user | kubectl apply -f -

这将安装带有 runasnonroot emissary 执行器的 argo。请注意，您仍然需要分析以 root 权限运行容器时可能出现的安全问题，并决定是否以 runasnonroot 方式运行 kubeflow pipeline 主容器。通常强烈建议所有用户可访问的 OCI 容器都遵循 Pod 安全标准的 restricted 级别。

多用户 Kubeflow Pipelines 依赖项

• Istio
• Kubeflow 角色
• OIDC 认证服务（或特定云提供商的认证服务）
• Profiles + KFAM

替代方案：Kubeflow Pipelines 独立版

您可以安装 Kubeflow Pipelines 独立版，它

• 不支持多用户隔离
• 不依赖于此处提到的其他服务

您可以在 Kubeflow Pipelines 安装选项 中了解它们的区别。

除了 Kubeflow Pipelines 独立版文档中的安装说明外，您还需要应用两个虚拟服务来暴露 Kubeflow Pipelines UI 和 Metadata API 到 kubeflow-gateway。

KServe

KFServing 已更名为 KServe。

安装 KServe 组件：

kustomize build contrib/kserve/kserve | kubectl apply -f -

安装 Models Web 应用程序：

kustomize build contrib/kserve/models-web-app/overlays/kubeflow | kubectl apply -f -

Katib

安装 Katib 官方 Kubeflow 组件：

kustomize build apps/katib/upstream/installs/katib-with-kubeflow | kubectl apply -f -

中央仪表板

安装中央仪表板官方 Kubeflow 组件：

kustomize build apps/centraldashboard/upstream/overlays/kserve | kubectl apply -f -

准入 Webhook

安装 PodDefaults 的准入 Webhook：

kustomize build apps/admission-webhook/upstream/overlays/cert-manager | kubectl apply -f -

Notebooks 1.0

安装 Notebook Controller 官方 Kubeflow 组件：

kustomize build apps/jupyter/notebook-controller/upstream/overlays/kubeflow | kubectl apply -f -

安装 Jupyter Web App 官方 Kubeflow 组件：

kustomize build apps/jupyter/jupyter-web-app/upstream/overlays/istio | kubectl apply -f -

工作区（Notebooks 2.0）

该功能仍在开发中。

PVC 查看器控制器

安装 PVC 查看器控制器官方 Kubeflow 组件：

kustomize build apps/pvcviewer-controller/upstream/default | kubectl apply -f -

Profiles + KFAM

安装 Profile Controller 和 Kubeflow 访问管理（KFAM）官方 Kubeflow 组件：

kustomize build apps/profiles/upstream/overlays/kubeflow | kubectl apply -f -

Volumes Web 应用程序

安装 Volumes Web App 官方 Kubeflow 组件：

kustomize build apps/volumes-web-app/upstream/overlays/istio | kubectl apply -f -

Tensorboard

安装 Tensorboards Web App 官方 Kubeflow 组件：

kustomize build apps/tensorboard/tensorboards-web-app/upstream/overlays/istio | kubectl apply -f -

安装 Tensorboard Controller 官方 Kubeflow 组件：

kustomize build apps/tensorboard/tensorboard-controller/upstream/overlays/kubeflow | kubectl apply -f -

训练操作器

安装训练操作器官方 Kubeflow 组件：

kustomize build apps/training-operator/upstream/overlays/kubeflow | kubectl apply -f -

用户命名空间

最后，为默认用户创建一个新的命名空间（名为 kubeflow-user-example-com）。

kustomize build common/user-namespace/base | kubectl apply -f -

连接到您的 Kubeflow 集群

安装后，所有 Pod 变为就绪状态需要一些时间。在尝试连接之前，请确保所有 Pod 都已就绪，否则可能会出现意外错误。要检查所有与 Kubeflow 相关的 Pod 是否就绪，请使用以下命令：

kubectl get pods -n cert-manager
kubectl get pods -n istio-system
kubectl get pods -n auth
kubectl get pods -n knative-eventing
kubectl get pods -n knative-serving
kubectl get pods -n kubeflow
kubectl get pods -n kubeflow-user-example-com

端口转发

访问 Kubeflow 的默认方式是通过端口转发。这使您可以快速入门，而不对您的环境施加任何要求。运行以下命令将 Istio 的 Ingress-Gateway 转发到本地端口 8080：

kubectl port-forward svc/istio-ingressgateway -n istio-system 8080:80

运行该命令后，您可以通过以下方式访问 Kubeflow 中央仪表板：

1. 打开浏览器并访问 http://localhost:8080。您应该会看到 Dex 登录界面。
2. 使用默认用户的凭据登录。默认电子邮件地址是 user@example.com，默认密码是 12341234。

NodePort / LoadBalancer / Ingress

为了使用 NodePort / LoadBalancer / Ingress 连接到 Kubeflow，您需要设置 HTTPS。原因是我们的许多 Web 应用程序（例如 Tensorboard Web 应用程序、Jupyter Web 应用程序、Katib UI）使用安全 Cookie，因此通过非本地主机域使用 HTTP 访问 Kubeflow 将无法正常工作。 使用适当的HTTPS暴露Kubeflow集群是一个简单的过程，但取决于您的环境。也有第三方商业发行版可供选择。

---

注意

如果您必须通过HTTP暴露Kubeflow，可以通过在每个相关的Web应用中将APP_SECURE_COOKIES环境变量设置为false来禁用安全Cookie功能。但不建议这样做，因为会带来安全风险。

---

更改默认用户名

出于安全考虑，在安全敏感的环境中安装时，我们不想使用默认的Kubeflow用户名和邮箱。相反，您应该在部署前定义自己的用户名和邮箱。为默认用户定义方法如下：

1. 编辑common/dex/overlays/oauth2-proxy/config-map.yaml，用您的邮箱和首选用户名填充相关字段：

   ...
     staticPasswords:
     - email: <替换为您的邮箱>
       username: <替换为您首选的用户名>

更改默认用户密码

出于安全考虑，在安全敏感的环境中安装时，我们不想使用默认的Kubeflow用户密码。相反，您应该定义自己的密码，并在创建集群之前或创建集群之后应用。

为默认用户（邮箱为user@example.com）选择一个密码，并使用bcrypt进行哈希处理：

```sh
python3 -c 'from passlib.hash import bcrypt; import getpass; print(bcrypt.using(rounds=12, ident="2y").hash(getpass.getpass()))'
```

例如，在本地运行上述命令（需要安装passlib等必要包）会如下所示：

python3 -c 'from passlib.hash import bcrypt; import getpass; print(bcrypt.using(rounds=12, ident="2y").hash(getpass.getpass()))'
Password:       <--- 在此处输入密码
$2y$12$vIm8CANhuWui0J1p3jYeGeuM28Qcn76IFMaFWvZCG5ZkKZ4MjTF4u <--- 输入密码生成的哈希值

创建集群之前：

1. 编辑common/dex/base/dex-passwords.yaml，用您选择的密码哈希值填充相关字段：

   ...
     stringData:
       DEX_USER_PASSWORD: <替换为哈希值>

创建集群之后：

1. 使用以下命令删除auth命名空间中现有的_dex-passwords_密钥：

   kubectl delete secret dex-passwords -n auth

2. 使用以下命令创建包含新哈希值的dex-passwords密钥：

   kubectl create secret generic dex-passwords --from-literal=DEX_USER_PASSWORD='替换为哈希值' -n auth

3. 使用以下命令重新创建auth命名空间中的_dex_ pod：

   kubectl delete pods --all -n auth

4. 尝试使用新的dex密码登录。

升级和扩展

对于Kubeflow平台的修改和就地升级，我们为高级用户提供了大致描述：

• 切勿直接编辑清单，请在example.yaml之上使用Kustomize覆盖和组件。
• 这样可以通过仅引用新的清单、使用kustomize构建并再次运行kubectl apply来进行升级。
• 如果需要，您可能需要调整顶层覆盖和组件。
• 您可能需要清理旧资源。为此，您应该从一开始就为所有资源添加标签。
• 使用标签，您可以使用kubectl apply加上--prune和--dry-run选项来列出可清理的资源。
• 有时会有重大变化，例如在1.9版本中我们切换到oauth2-proxy，这需要额外注意。
• 尽管如此，只要有一些Kubernetes知识，就应该能够进行升级。

发布流程

Manifest工作组根据发布时间表发布Kubeflow。 社区和发布团队在发布周期开始时与Manifest工作组密切合作，确定具体日期， 并遵循发布版本策略， 这些都在Kubeflow发布手册中定义。

CVE扫描

要查看所有过去的安全扫描，请前往镜像提取和安全扫描GitHub Action工作流。在工作流日志中，您可以展开运行镜像提取和安全扫描脚本步骤来查看CVE日志。您会找到每个镜像的CVE扫描结果和按工作组聚合的指标JSON转储。 您可以在本地机器上运行工作流文件中的Python脚本，以获取任何git提交的详细JSON文件。

Kubeflow安全工作组遵循CVE结果的负责任披露政策：

• 内部审查：所有CVE发现最初由安全工作组内部审查。
• 严重性评估：对每个CVE进行严重性和对Kubeflow项目潜在影响的评估。
• 披露：对于高危和关键严重性的CVE，安全工作组将：
  • 通知维护者和贡献者
  • 尝试提供修复或缓解策略
  • 公开披露CVE详细信息

常见问题

• **问：**哪些版本的Istio、Knative、Cert-Manager、Argo等与Kubeflow兼容？
  **答：**请参考每个单独组件的文档以了解依赖兼容性范围。对于Istio、Knative、Dex、Cert-Manager和OAuth2 Proxy，common中的版本是我们已验证的版本。
• **问：**我可以在Kubeflow清单中使用早期版本的Kustomize吗？ **答：**不再支持这样做，尽管通过手动努力可能实现。