GPUStack 2.2.2 Kubernetes 部署文档

作者吴业亮博客wuyeliang.blog.csdn.net1. 部署概览项目实际配置目标主机192.168.1.31操作系统Ubuntu 22.04.5 LTSKubernetesv1.30.14kubeadm 单节点集群容器运行时containerd 1.7.27Helmv3.18.4GPUNVIDIA GeForce RTX 409024 GiBGPUStackv2.2.2CNIFlannel v0.25.5GPU 运行时NVIDIA Container Toolkit 1.17.8GPUStack 命名空间gpustack-systemHelm ReleasegpustackGPUStack 官方 Helm 部署要求 Kubernetes 1.30、Helm 3.18.4。官方文档https://docs.gpustack.ai/latest/installation/helm/2. 网络前提目标主机无法直接访问 Kubernetes 官方镜像仓库的后端地址因此 containerd 使用了主机已有的代理http://192.168.1.119:7890containerd 配置文件/etc/systemd/system/containerd.service.d/http-proxy.conf内容[Service] EnvironmentHTTP_PROXYhttp://192.168.1.119:7890 EnvironmentHTTPS_PROXYhttp://192.168.1.119:7890 EnvironmentNO_PROXY127.0.0.1,localhost,192.168.1.31,10.0.0.0/8,10.96.0.0/12,172.16.0.0/12,192.168.0.0/16应用配置systemctl daemon-reload systemctl restart containerd目标主机没有可用 IPv6 出站路径因此设置了/etc/sysctl.d/99-disable-ipv6-k8s.confnet.ipv6.conf.all.disable_ipv6 1 net.ipv6.conf.default.disable_ipv6 13. 安装 Kubernetes 软件包以下命令使用 Kubernetes 官方 v1.30 软件源exportDEBIAN_FRONTENDnoninteractiveapt-getupdateapt-getinstall-yapt-transport-https ca-certificatescurlgpginstall-d-m0755 /etc/apt/keyringscurl-fsSLhttps://pkgs.k8s.io/core:/stable:/v1.30/deb/Release.key\|gpg--dearmor--yes-o/etc/apt/keyrings/kubernetes-apt-keyring.gpgechodeb [signed-by/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.30/deb/ /\/etc/apt/sources.list.d/kubernetes.listapt-getupdateapt-getinstall-ykubelet kubeadm kubectl apt-mark hold kubelet kubeadm kubectl验证kubeadm version-oshort kubectl version--clienttrue本次版本为v1.30.14。4. 配置 containerd确保 containerd 使用 systemd cgroupmkdir-p/etc/containerd containerd config default/etc/containerd/config.tomlsed-is/SystemdCgroup false/SystemdCgroup true//etc/containerd/config.toml systemctl restart containerd验证 CRIcrictl --runtime-endpoint unix:///run/containerd/containerd.sock info5. 配置 Kubernetes 内核参数swapoff-amodprobe overlay modprobe br_netfiltercat/etc/modules-load.d/k8s.confEOF overlay br_netfilter EOFcat/etc/sysctl.d/99-kubernetes-cri.confEOF net.bridge.bridge-nf-call-iptables 1 net.bridge.bridge-nf-call-ip6tables 1 net.ipv4.ip_forward 1 EOFsysctl--system6. 拉取 Kubernetes 基础镜像先验证官方镜像拉取kubeadm config images pull\--kubernetes-versionv1.30.14\--cri-socketunix:///run/containerd/containerd.sock7. 初始化单节点 Kuberneteskubeadm init\--kubernetes-versionv1.30.14\--apiserver-advertise-address192.168.1.31\--pod-network-cidr10.244.0.0/16\--cri-socketunix:///run/containerd/containerd.sock配置 root 用户的 kubeconfigmkdir-p/root/.kubecp/etc/kubernetes/admin.conf /root/.kube/configexportKUBECONFIG/etc/kubernetes/admin.conf8. 部署 Flannel CNIkubectl apply-f\https://raw.githubusercontent.com/flannel-io/flannel/v0.25.5/Documentation/kube-flannel.yml单节点允许调度普通工作负载kubectl taint nodes--allnode-role.kubernetes.io/control-plane-验证kubectl get nodes-owide kubectl get pods-A9. 安装 Helm 3.18.4tmpdir$(mktemp-d)HTTPS_PROXYhttp://192.168.1.119:7890\curl-fsSLhttps://get.helm.sh/helm-v3.18.4-linux-amd64.tar.gz\|tar-xz-C$tmpdirinstall-m0755$tmpdir/linux-amd64/helm/usr/local/bin/helmrm-rf$tmpdirhelm version--short10. 配置 NVIDIA containerd runtime目标机已安装 NVIDIA Container Toolkit。使用nvidia-ctk写入 containerd 配置nvidia-ctk runtime configure\--runtimecontainerd\--config/etc/containerd/config.toml systemctl restart containerd11. 安装 Node Feature Discoveryhelm repoaddnfd\https://kubernetes-sigs.github.io/node-feature-discovery/charts helm repo update helm upgrade--installnfd nfd/node-feature-discovery\--version0.18.3\--namespacenode-feature-discovery\--create-namespace\--wait\--timeout300s验证kubectl get pods-nnode-feature-discovery kubectl getnode--show-labels12. 创建 NVIDIA RuntimeClassGPUStack 2.2.2 的 NVIDIA worker 使用名为nvidia的 RuntimeClassapiVersion:node.k8s.io/v1kind:RuntimeClassmetadata:name:nvidiahandler:nvidia应用kubectl apply-fnvidia-runtimeclass.yaml或者直接执行kubectl apply-f-EOF apiVersion: node.k8s.io/v1 kind: RuntimeClass metadata: name: nvidia handler: nvidia EOF13. 补充 GPUStack 兼容标签NFD 在本机生成的 NVIDIA PCI 标签为feature.node.kubernetes.io/pci-0300_10de.presenttrueGPUStack 2.2.2 的 worker selector 使用pci-10de.present因此补充兼容标签kubectl labelnodeubuntu\feature.node.kubernetes.io/pci-10de.presenttrue\--overwrite14. 安装 GPUStack 2.2.2本次使用官方 OCI Helm chart并启用 NVIDIA workerHTTPS_PROXYhttp://192.168.1.119:7890\helm upgrade--installgpustack\oci://registry-1.docker.io/gpustack/gpustack-chart\--version2.2.2\--namespacegpustack-system\--create-namespace\--setserver.dataVolume.hostPath/var/lib/gpustack\--setworker.enabledtrue\--setworker.gpuVendors{nvidia}\--timeout120s说明使用server.dataVolume.hostPath避免单节点环境依赖额外 StorageClass。worker.enabledtrue启用 GPUStack worker DaemonSet。worker.gpuVendors{nvidia}启用 NVIDIA worker。GPUStack chart 会同时部署 Higress、operator、NFD、Kueue 和 CSI 相关组件。15. 部署验收查看 Helm releasehelm status gpustack-ngpustack-system本次最终状态NAME: gpustack NAMESPACE: gpustack-system STATUS: deployed REVISION: 3查看 Podkubectl get pods-ngpustack-system-owide核心组件应为 Running/Readygpustack-server-0gpustack-worker-nvidia-*gpustack-higress-plugins-*higress-controller-*higress-gateway-*gpustack-operator-device-manager-nvidia-*验证 GPU 资源kubectl describenodeubuntu|grep-Envidia.com/gpu|Capacity|Allocatable-A8本次节点资源nvidia.com/gpu: 1 nvidia.com/gpu.shared: 10验证 GPU workerkubectl rollout status\daemonset/gpustack-worker-nvidia\-ngpustack-system\--timeout600s验证 HTTP 访问curl-ihttp://192.168.1.31:30149/本次返回HTTP 20016. GPUStack 登录信息访问http://192.168.1.31:30149用户名admin本次部署生成的初始密码mAbpMBxA%bJ7也可以在主机上重新读取kubectlexec-ngpustack-system gpustack-server-0 --\cat/var/lib/gpustack/initial_admin_password首次登录后应立即修改初始密码。17. 常用运维命令查看所有资源kubectl get all-ngpustack-system查看事件kubectl get events-ngpustack-system --sort-by.lastTimestamp查看 GPUStack Server 日志kubectl logs-ngpustack-system gpustack-server-0查看 GPU worker 日志kubectl logs-ngpustack-system\-lapp.kubernetes.io/componentworker\--tail200查看设备管理器日志kubectl logs-ngpustack-system\-lapp.kubernetes.io/componentdevice-manager\--all-containers\--tail200查看 containerd 日志journalctl-ucontainerd-n100--no-pager18. 常见问题18.1 kubeadm 拉取镜像超时确认 containerd 已加载代理systemctl show containerd--propertyEnvironment systemctl restart containerd然后重新执行kubeadm config images pull\--kubernetes-versionv1.30.14\--cri-socketunix:///run/containerd/containerd.sock18.2 GPU worker 提示 RuntimeClass 不存在确认资源存在kubectl get runtimeclass nvidia不存在时重新创建第 12 节中的 RuntimeClass。18.3 GPU worker 没有 Pod检查节点标签kubectl getnodeubuntu --show-labels|greppci-10de如果缺少标签kubectl labelnodeubuntu\feature.node.kubernetes.io/pci-10de.presenttrue\--overwrite18.4 节点没有 nvidia.com/gpu 资源确认 NVIDIA runtime 和设备管理器command-vnvidia-container-runtimecommand-vnvidia-ctk kubectl get pods-ngpustack-system|grepdevice-manager kubectl logs-ngpustack-system\-lapp.kubernetes.io/componentdevice-manager\--all-containers主机侧确认 GPUnvidia-smi-L18.5 CSI Pod 处于 ContainerCreatingCSI 组件依赖多个镜像首次安装时可能需要较长时间拉取。查看具体原因kubectl get events-ngpustack-system --sort-by.lastTimestamp kubectl describe pod-ngpustack-systempod-name如果 GPUStack Server、Higress 和 NVIDIA worker 已 ReadyCSI 组件的短暂收敛不会影响控制台和 GPU worker 基础功能。19. 卸载卸载 Helm releasehelm uninstall gpustack-ngpustack-system删除命名空间kubectl delete namespace gpustack-system注意删除命名空间会删除 GPUStack 资源。主机路径/var/lib/gpustack不会由 Helm 自动清理删除前请先确认是否需要保留模型和数据库数据。20. 引入 HAMi20.1 兼容性说明HAMi 的 device-plugin 和 GPUStack 的 GPU device manager 都可能注册nvidia.com/gpu。同一节点同时运行两个 device-plugin 会造成 GPU 资源注册冲突因此本环境采用 HAMi 的安全引入模式启用 HAMi scheduler启用 HAMi admission webhook关闭 HAMi device-plugin继续由 GPUStack device manager 管理 GPU 资源HAMi 官方也说明同一节点不应同时运行两个 NVIDIA GPU device-pluginhttps://project-hami.io/docs/faq20.2 安装 HAMi 2.9.0给 GPU 节点添加 HAMi 标签kubectl labelnodeubuntugpuon--overwrite添加 HAMi 官方 Helm 仓库helm repoaddhami-charts https://project-hami.github.io/HAMi/ helm repo update安装 HAMi关闭 device-pluginhelm upgrade--installhami hami-charts/hami\--version2.9.0\--namespacekube-system\--setdevicePlugin.enabledfalse\--wait\--timeout600s20.3 验证 HAMihelm status hami-nkube-system kubectl get pods-nkube-system\-lapp.kubernetes.io/instancehami\-owide kubectl get mutatingwebhookconfiguration hami-webhook本次验证结果Release hami: deployed hami-scheduler: 2/2 Running HAMi webhook: createdHAMi 服务端口443:31998/TCP 31993:31993/TCP20.4 当前 GPU 资源状态kubectl describenodeubuntu|grep-Envidia.com/gpu|nvidia.com/gpu.shared-A2当前节点仍由 GPUStack device manager 提供资源nvidia.com/gpu: 1 nvidia.com/gpu.shared: 1020.5 HAMi 完整 GPU 分片模式如果后续需要 HAMi device-plugin 真正接管 GPU 分片不能直接执行默认安装。必须先规划并停用 GPUStack 的 GPU device manager然后再执行helm upgrade hami hami-charts/hami\--version2.9.0\--namespacekube-system\--setdevicePlugin.enabledtrue\--wait\--timeout600s这会改变nvidia.com/gpu的资源所有权可能影响 GPUStack worker 和已经运行的 GPU workload。生产环境应先停机或迁移 workload并在变更后重新验证 GPUStack 的 worker 注册和模型服务。HAMi 官方 Helm 安装参考https://project-hami.io/docs/next/get-started/deploy-with-helm