轻量级实战：利用 K3s 和 Kubeflow 构建高效 AI 开发环境

1. 为什么你需要一个轻量级的本地AI开发环境如果你正在学习机器学习或者在一个小团队里捣鼓AI模型我猜你肯定遇到过这样的烦恼每次想跑个实验要么得去申请云上的GPU实例流程繁琐不说成本还高要么就是在自己那台老旧的笔记本上吭哧吭哧地装TensorFlow、PyTorch结果环境冲突、依赖缺失半天时间就搭进去了模型还没开始训练。更别提想体验一下完整的MLOps流程比如模型版本管理、流水线自动化、超参数调优这些“高级货”了感觉离自己特别遥远。其实这些痛点背后是一个共同的需求我们想要一个开箱即用、资源消耗小、功能又足够全的AI开发平台。它最好能跑在我的MacBook或者一台普通的Linux开发机上让我能随时随地进行模型实验同时又能接触到接近生产环境的工具链。这就是我今天想跟你分享的“轻量级组合拳”K3s Kubeflow。简单来说K3s是一个极度轻量化的Kubernetes发行版它把K8s这个“庞然大物”精简到了极致只需要几百兆内存就能跑起来特别适合边缘计算和本地开发。而Kubeflow则是构建在Kubernetes之上的机器学习工具包它把数据准备、模型训练、超参调优、模型部署等一系列流程都打包成了可复用的组件。把它们俩结合起来你就能在本地轻松拥有一个功能强大的AI工作站。我自己的体验是用这套方案在一台配置还不错的MacBook Pro我给了Docker Desktop 8核CPU和16GB内存上从零开始到能打开Kubeflow的Web界面运行Jupyter Notebook大概也就一个小时。这比在云上折腾虚拟机、配置网络、管理账单要直接得多也便宜得多——毕竟电费比云服务费便宜多了。接下来我就带你一步步把它搭建起来并分享一些我踩过坑后总结的实用技巧。2. 搭建前的准备资源规划与工具选型在动手之前我们得先盘算一下手里的“粮草”。虽然K3s很轻量但Kubeflow毕竟是一整套系统包含了Istio服务网格、Argo工作流、MinIO对象存储等一大堆组件对资源还是有一定要求的。2.1 硬件与软件资源建议根据我多次安装的经验我给你一个比较稳妥的配置建议CPU至少4核建议8核。因为编译镜像、启动多个Pod时CPU密集型操作不少。内存最低8GB强烈建议16GB或以上。我最初用8GB内存的机器尝试安装过程中Pod频繁因为内存不足OOM被杀死过程非常痛苦。16GB可以保证比较流畅的体验。磁盘空间至少预留40GB的可用空间。Docker镜像、PV持久卷都会占用不少空间。操作系统macOS、LinuxUbuntu CentOS都可以。本文以macOS为例Linux下的操作几乎完全一致。关键软件Docker Desktop或Rancher Desktop这是运行容器的引擎。在Mac上我习惯用Docker Desktop记得在它的设置Preferences - Resources里把资源分配调整到我们建议的规格。HomebrewmacOS的包管理器用来安装其他命令行工具。这里有个小坑我得提醒你不要被K3s的“轻量”迷惑以为它对宿主机的资源需求也很低。K3s本身确实轻但它要承载的Kubeflow组件可不轻。所以务必在Docker Desktop里把资源给足否则安装过程会卡在Pending状态让你排查到怀疑人生。2.2 为什么选择deployKF这个发行版原始文章里提到了使用deployKF这是一个非常明智的选择。Kubeflow的安装方式有好几种比如kfctl、Kubeflow Manifests但deployKF是目前对新手最友好、对自定义支持也最好的方式之一。你可以把它理解为Kubeflow的一个“豪华集成安装包”。它做了几件很棒的事基于Argo CD采用“GitOps”的方式管理部署。所有配置都通过YAML文件定义安装和升级就像提交代码一样清晰、可回溯。高度模块化它把Kubeflow的各个组件如Pipelines、Katib、Notebooks以及依赖如Istio、Cert-Manager都做成了可插拔的模块。你可以通过一个统一的配置文件轻松选择启用或禁用某个功能不用再面对一堆令人眼花缭乱的独立部署文件。提供生产就绪的默认值比如自动配置HTTPS证书、安全的身份认证Dex OAuth2 Proxy等这些如果自己从零搭建会非常复杂。所以跟着本文使用deployKF你能避开至少80%的配置陷阱。接下来我们就进入实战环节。3. 实战第一步搭建轻量级Kubernetes集群K3s有了Docker Desktop我们其实可以直接用k3d这个工具。k3d能让你在Docker容器里运行K3s集群这比直接在宿主机上安装还要方便清理起来也彻底非常适合做实验。首先打开你的终端用Homebrew把需要的命令行工具一次性装好brew install bash argocd jq k3d kubectl kustomize这些工具的作用分别是bash: 确保我们使用较新版本的bash。argocd: Argo CD的命令行客户端用来管理部署。jq: 处理JSON数据的利器后面查密码什么的会用上。k3d: 核心工具用于创建和管理K3s集群。kubectl: Kubernetes集群的管理命令行工具必须的。kustomize: 用来定制Kubernetes YAML配置的工具deployKF会用到。工具安装完毕现在创建一个单节点的K3s集群我们给它起名叫kubeflowk3d cluster create kubeflow --image rancher/k3s:v1.27.10-k3s2这个命令会从Docker Hub拉取指定版本的K3s镜像并在容器内启动一个集群。v1.27.10是一个比较稳定且与Kubeflow兼容性好的Kubernetes版本。执行完成后kubectl的上下文context会自动切换到k3d-kubeflow这意味着你后续的所有kubectl命令都是针对这个本地集群的。怎么验证集群是否健康呢运行kubectl get pods -A你应该会看到kube-system命名空间下有一些系统Pod在运行比如coredns、traefikIngress控制器、local-path-provisioner本地存储类等。如果它们的状态都是Running那么恭喜你一个轻量级的Kubernetes游乐场已经准备就绪了。这比用minikube或者kind启动一个完整K8s集群要快得多也省资源得多。4. 部署Argo CD与deployKF工作流集群有了接下来我们要请出两位“管家”Argo CD和deployKF。Argo CD负责持续部署deployKF则定义了部署Kubeflow的具体内容和步骤。4.1 安装Argo CD我们按照deployKF官方推荐的方式使用其提供的插件脚本来安装Argo CD。这样能确保版本和配置的兼容性。git clone -b main https://github.com/deployKF/deployKF.git cd deployKF/argocd-plugin chmod x ./install_argocd.sh bash ./install_argocd.sh这个脚本会在你的集群里创建一个名为argocd的命名空间并把Argo CD的所有组件部署进去。安装完成后检查一下Pod的状态kubectl get pod -n argocd稍等一两分钟所有Pod都应该进入Running状态。Argo CD提供了一个Web UI我们可以通过端口转发来访问它kubectl port-forward --namespace argocd svc/argocd-server 8090:https现在用浏览器打开https://localhost:8090。首次登录的用户名是admin密码需要从Kubernetes的一个Secret中获取。在终端里执行这个命令来获取密码echo $(kubectl -n argocd get secret/argocd-initial-admin-secret -o jsonpath{.data.password} | base64 -d)把输出的密码粘贴到登录页面你就进入了Argo CD的控制台。不过先别急着重启我们还需要配置一个最重要的东西——告诉Argo CD要去部署什么。4.2 创建并部署deployKF的“Application of Applications”这是整个安装过程的核心。deployKF使用一种叫做“App of Apps”的模式。简单理解就是我们创建一个主应用Application这个主应用本身并不直接部署Kubeflow而是定义了多个子应用比如Istio、Cert-Manager、Kubeflow Pipelines等然后由Argo CD去同步这些子应用。这种模式让管理变得非常清晰。首先回到deployKF的根目录我们创建一个配置文件。你可以直接使用项目提供的样例文件但为了理解我们最好自己创建一个。在任意位置创建一个名为deploykf-app-of-apps.yaml的文件内容如下apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: deploykf-app-of-apps namespace: argocd labels: app.kubernetes.io/name: deploykf-app-of-apps app.kubernetes.io/part-of: deploykf spec: project: default source: repoURL: https://github.com/deployKF/deployKF.git targetRevision: v0.1.4 # 使用稳定的版本标签 path: . plugin: name: deploykf parameters: - name: source_version string: 0.1.4 - name: values_files array: - ./sample-values.yaml - name: values string: | # 在这里你可以覆盖 sample-values.yaml 中的默认配置 # 例如如果你想禁用某个组件可以在这里设置 # kubeflow_tools: # katib: # enabled: false destination: server: https://kubernetes.default.svc namespace: argocd这个YAML文件做了几件事它定义了一个Argo CD应用名字叫deploykf-app-of-apps。指定了配置来源是deployKF的Git仓库并使用v0.1.4这个版本请务必检查GitHub仓库的最新稳定版。使用deploykf这个Argo CD插件来生成最终的Kubernetes清单。插件会读取sample-values.yaml作为基础配置并合并我们在values字段下提供的任何覆盖配置。将生成的资源部署到当前集群的argocd命名空间下。注意values字段下的配置是递归合并的。这意味着你只需要定义你想修改的部分。例如如果你想关闭超参数优化工具Katib就像注释里写的那样取消注释并设置enabled: false即可。这比直接修改庞大的sample-values.yaml要安全方便得多。保存文件后使用kubectl应用它kubectl apply -f ./deploykf-app-of-apps.yaml现在回到Argo CD的Web界面如果端口转发断了就重新执行kubectl port-forward你应该能看到一个名为deploykf-app-of-apps的应用出现了。它的状态可能是OutOfSync不同步。这是因为我们创建了应用定义但还没有告诉Argo CD去同步它。4.3 执行同步安装所有组件你可以点击UI界面上的“SYNC”按钮来手动同步。但更推荐使用deployKF提供的自动化脚本因为它能按照正确的依赖顺序来同步各个子应用避免出错。cd /path/to/deployKF/scripts chmod x ./sync_argocd_apps.sh bash ./sync_argocd_apps.sh这个脚本会依次同步deploykf-dependencies如Cert-Manager, Istio、deploykf-core核心认证和网关、deploykf-optMinIO, MySQL和kubeflow-tools各种Kubeflow组件。整个过程可能需要15到30分钟具体取决于你的网络速度和机器性能。期间你可以通过以下命令观察Pod的启动情况watch kubectl get pods -A你会看到大量的Pod被创建并经历ContainerCreating、Pending等待调度最终到Running的状态。这是最考验耐心的一步。如果某些Pod长时间卡在Pending多半是资源尤其是内存不足请回头检查Docker Desktop的资源分配。当脚本执行完毕并且你看到所有关键Pod特别是istiod、deploykf-gateway、各个Kubeflow组件都处于Running状态时安装就基本成功了。此时Argo CD界面中所有20个左右的应用都应该显示为绿色的Synced和Healthy状态。5. 访问你的本地Kubeflow平台组件都跑起来了我们怎么访问呢Kubeflow通过Istio Gateway来暴露服务我们需要做两件事端口转发和本地域名解析。首先转发Istio Gateway的端口到本地kubectl port-forward --namespace deploykf-istio-gateway svc/deploykf-gateway 8080:http 8443:https这个命令将集群内的Gateway服务的80和443端口分别映射到了本地的8080和8443端口。其次因为Gateway会根据访问的域名Host Header把流量路由到不同的后端服务比如Kubeflow中央面板、Argo Workflows UI、MinIO控制台我们需要在本地/etc/hosts文件里添加一些记录。用你喜欢的编辑器比如sudo vim /etc/hosts打开它在末尾添加127.0.0.1 deploykf.example.com 127.0.0.1 argo-server.deploykf.example.com 127.0.0.1 minio-api.deploykf.example.com 127.0.0.1 minio-console.deploykf.example.com现在打开浏览器访问https://deploykf.example.com:8443。由于我们用的是自签名证书浏览器会提示不安全点击“高级”-“继续前往”即可。你会看到Kubeflow的登录界面。deployKF默认创建了几个测试用户管理员adminexample.com/admin普通用户1user1example.com/user1普通用户2user2example.com/user2用管理员账号登录一个功能丰富的Kubeflow仪表盘就呈现在你眼前了你可以在这里创建Jupyter Notebook服务器运行机器学习流水线进行超参数调优实验等等。6. 开始你的第一个AI任务运行Jupyter Notebook登录后最常用的起点就是“Notebooks”模块。点击左侧导航栏的“Notebooks”然后点击“ New Notebook”。给Notebook服务器起个名字比如my-first-ai-lab。选择镜像deployKF通常预置了一些包含常用ML框架TensorFlow, PyTorch的镜像。你可以选择一个带有GPU支持的镜像如果你本地有GPU且配置了驱动或者一个普通的CPU镜像。分配资源根据你的任务需求调整CPU、内存的请求值。对于简单的模型实验2核CPU、4GB内存是个不错的起点。创建存储卷这是一个好习惯。添加一个PVC持久卷声明这样你Notebook里的数据和工作成果在服务器重启后也不会丢失。你可以选择创建一个新的或者挂载已有的。点击“LAUNCH”。稍等片刻Notebook服务器的状态会从“Pending”变为“Running”。点击旁边的“Connect”按钮就会在新的标签页中打开熟悉的JupyterLab界面了现在你可以像在本地一样创建Python Notebook安装额外的包开始你的模型训练了。所有的计算都发生在你本地的K3s集群容器里环境是隔离且可复现的。7. 进阶配置与日常维护技巧平台搭起来只是开始要想用得顺手还得了解一些进阶操作和避坑指南。7.1 如何自定义安装组件也许你不需要全套的Kubeflow。比如你只想要Notebook和Pipelines不需要Katib超参数优化和KFServing模型部署。这时你就可以修改我们之前创建的deploykf-app-of-apps.yaml文件中的values部分。- name: values string: | kubeflow_tools: katib: enabled: false pipelines: enabled: true notebooks: enabled: true # 其他工具按需关闭 # kserve: # enabled: false修改后再次应用这个YAML文件并重新运行同步脚本。Argo CD会计算出配置差异并只更新必要的部分禁用掉的组件会被删除。这能帮你节省不少资源。7.2 访问其他服务界面除了主面板你可能还需要访问Argo Workflows UI用于查看和调试机器学习流水线。访问https://argo-server.deploykf.example.com:8443。注意这个地址和我们之前配的hosts条目对应。MinIO控制台Kubeflow默认使用MinIO作为实验数据和模型文件的存储。访问https://minio-console.deploykf.example.com:8443。默认的用户名密码通常是minioadmin/minioadmin你可以在deployKF的values配置中修改。7.3 关机与重启当你用完想关机时直接关闭终端里的kubectl port-forward命令即可集群还在后台运行。如果想彻底关闭整个环境以释放资源可以运行k3d cluster stop kubeflow # 暂停集群 k3d cluster start kubeflow # 启动集群 k3d cluster delete kubeflow # 彻底删除集群所有数据会丢失重要提醒使用k3d cluster delete会删除整个集群包括所有PVC里的数据。所以重要的代码和模型文件一定要保存在Git仓库或者挂载到宿主机的持久卷中。7.4 遇到问题怎么办安装过程很少一帆风顺。这里有几个排查思路查看Pod日志kubectl logs -n namespace pod-name是定位问题最直接的方法。描述Pod状态kubectl describe pod -n namespace pod-name可以看Pod无法启动的具体原因比如是不是镜像拉取失败、资源不足、节点选择器不匹配等。检查Argo CD同步状态在UI里查看哪个应用同步失败了点进去看详细日志。资源永远是第一嫌疑犯90%的安装卡顿都是内存不足导致的。务必确保Docker Desktop分配了足够资源并检查宿主机本身是否有足够空闲内存。我在自己的M1 Mac上第一次安装时就因为内存只给了8GB导致istiod等组件反复崩溃。后来把内存加到16GB问题迎刃而解。所以如果你的安装卡住了先别急着查复杂的配置看看资源监控说不定就是内存爆了。