企业官网建设流程全解析

在 minikube 中使用 AMD GPU：基于 docker 驱动开启 amd.com/gpu 设备插件支持

【免费下载链接】minikubeRun Kubernetes locally项目地址: https://gitcode.com/gh_mirrors/mi/minikube

本教程基于 site/content/en/docs/tutorials/amd.md 编写，讲解如何让 minikube 集群内的 Pod 直接使用宿主机上的 AMD 显卡（ROCm 生态），核心能力来自 Kubernetes 的 AMD GPU 设备插件（k8s-device-plugin）。读完本文，你将掌握从环境检查、minikube start --gpus amd启动、到提交 Job 验证 GPU 可用的完整流程，并理解 GPU 透传在 minikube 内部的实现原理与平台限制。

前置条件

在开始之前，请确保环境满足以下要求：

需要特别说明的是，AMD GPU 支持目前仅限 docker 驱动 + docker 容器运行时组合，这是由源码层面的校验逻辑强制保证的（详见下文"参数校验"一节），其他驱动（如 KVM、VirtualBox）或 containerd/cri-o 运行时均不支持。

第一步：确认 AMD 驱动已正确安装

minikube 的 GPU 支持建立在宿主机已有可用 AMD 驱动的基础之上。可以通过rocminfo命令检查驱动是否就绪：

rocminfo

如果命令执行失败或未找到该命令，说明驱动尚未安装，请按照 AMD 官方的 Radeon™ 驱动安装指南（Radeon™ Driver Installation Guide）完成安装后再继续。驱动正常工作时，rocminfo会列出系统里的 CPU/GPU HSA Agent 以及 ROCm 运行时版本等信息。

第二步：清理旧的 minikube 实例（可选）

如果你在安装 AMD 驱动之前已经创建过 minikube 集群，建议先删除旧实例，避免旧节点容器在启动时无法挂载新安装的 GPU 设备节点：

minikube delete

这一步是可选的：只有当已有实例是在安装驱动前构建的，才需要清理。

第三步：以 AMD GPU 模式启动 minikube

使用--gpus amd标志启动集群：

minikube start --driver docker --container-runtime docker --gpus amd

该命令显式指定了 docker 驱动和 docker 容器运行时，并把 AMD GPU 透传进 minikube 节点容器。

--gpus标志的取值与校验逻辑

--gpus（短标志-g）是minikube start的一个全局选项，源码定义在 start_flags.go：

startCmd.Flags().StringP(gpus, "g", "", "Allow pods to use your GPUs. Options include: [all,nvidia,amd] (Docker driver with Docker container-runtime only)")

可接受的值包括all、nvidia、nvidia.com、amd。对应的校验函数validateGPUs位于 start.go，其约束可以总结为三点：

1. 取值白名单：只接受nvidia、nvidia.com、amd、all，否则报错The gpus flag must be passed a value of "nvidia", "nvidia.com", "amd" or "all"；
2. 驱动与运行时组合：必须是docker驱动且容器运行时为docker，否则报错The gpus flag can only be used with the docker driver and docker container-runtime；
3. 宿主架构：仅支持amd64、arm64、ppc64le三种架构（见validateGPUsArch）。

这些约束同样在单元测试 start_test.go 中被覆盖验证，例如传入amd+ docker 驱动 + containerd 运行时会返回错误。

底层实现：GPU 设备如何透传进节点容器

启动时--gpus的值会一路从命令行配置（pkg/minikube/config/types.go 中的GPUs字段）传递到 KIC（Kubernetes in Container）驱动的节点创建流程，见 pkg/drivers/kic/kic.go。

最终在 pkg/drivers/kic/oci/oci.go 中，根据取值生成对应的容器运行参数：

switch p.GPUs { case "all", "nvidia": runArgs = append(runArgs, "--gpus", "all", "--env", "NVIDIA_DRIVER_CAPABILITIES=all") case "nvidia.com": runArgs = append(runArgs, "--device", "nvidia.com/gpu=all") case "amd": /* https://rocm.docs.amd.com/projects/install-on-linux/en/latest/how-to/docker.html * "--security-opt seccomp=unconfined" is also required but included above. */ runArgs = append(runArgs, "--device", "/dev/kfd", "--device", "/dev/dri", "--group-add", "video", "--group-add", "render") }

可以看到，amd模式会把宿主机的/dev/kfd（Kernel Fusion Driver，ROCm 的核心内核驱动设备）和/dev/dri（DRM 渲染设备）直接挂载进节点容器，并把容器加入video与render组以获取对应设备的访问权限；同时容器以--privileged和--security-opt seccomp=unconfined方式运行，保证 ROCm 用户态栈可以正常访问 GPU 设备。

设备插件自动部署：amd-gpu-device-plugin addon

--gpus amd启动时，minikube 会自动启用amd-gpu-device-pluginaddon（对应配置见 pkg/addons/config.go）。该 addon 由 pkg/minikube/assets/addons.go 注册，默认拉取rocm/k8s-device-plugin镜像，其实际部署清单是 deploy/addons/gpu/amd-gpu-device-plugin.yaml.tmpl：

• 以DaemonSet形式在每个节点上运行一个设备插件 Pod，通过 hostPath 挂载/var/lib/kubelet/device-plugins与 kubelet 通信，并挂载/sys用于枚举 GPU 设备；
• 设置了system-node-critical优先级与CriticalAddonsOnly容忍，确保设备插件随集群核心组件一同就绪；
• 设备插件向 kubelet 注册后，集群内就会出现名为amd.com/gpu的可分配资源，Pod 即可通过resources.limits["amd.com/gpu"]申请 GPU（当前模板仅面向amd64架构的节点）。

验证 GPU 在集群内可用

启动完成后，可以通过创建一个请求 GPU 的 Job 来验证 AMD GPU 是否真正可用。

1. 创建 GPU 检查 Job

cat <<'EOF' | kubectl apply -f - apiVersion: batch/v1 kind: Job metadata: name: amd-gpu-check labels: purpose: amd-gpu-check spec: ttlSecondsAfterFinished: 100 template: spec: restartPolicy: Never securityContext: supplementalGroups: - 44 - 110 containers: - name: amd-gpu-checker image: rocm/rocm-terminal workingDir: /root command: ["rocminfo"] args: [] resources: limits: amd.com/gpu: 1 # requesting a GPU EOF

关键点说明：

• resources.limits["amd.com/gpu": 1]是向调度器声明"本 Pod 需要 1 块 AMD GPU"，只有启用了设备插件后该资源名才存在，这也是验证设备插件是否生效的最直接方式；
• supplementalGroups中的 44（video）与 110（render）与上文中节点容器追加的--group-add video --group-add render保持一致，确保容器内的rocminfo能以正确的组权限访问/dev/kfd与/dev/dri；
• command: ["rocminfo"]让容器启动后直接执行 ROCm 自带的 GPU 信息查询工具；
• ttlSecondsAfterFinished: 100让 Job 在完成后 100 秒自动被清理。

2. 查看 Job 日志

kubectl logs jobs/amd-gpu-check

如果一切正常，输出应类似下面这样——能看到 ROCk 内核模块版本、HSA 系统属性以及具体的 GPU Agent（示例环境为带 Radeon 780M 核显的 AMD Ryzen 7 7840U）：

ROCk module version 6.8.5 is loaded ===================== HSA System Attributes ===================== Runtime Version: 1.14 Runtime Ext Version: 1.6 System Timestamp Freq.: 1000.000000MHz Sig. Max Wait Duration: 18446744073709551615 (0xFFFFFFFFFFFFFFFF) (timestamp count) Machine Model: LARGE System Endianness: LITTLE Mwaitx: DISABLED DMAbuf Support: YES ========== HSA Agents ========== ******* Agent 1 ******* Name: AMD Ryzen 7 7840U w/ Radeon 780M Graphics Uuid: CPU-XX ...

日志中出现完整的 HSA Agent 列表（尤其是带有 GPU 型号名称的条目），即表示 GPU 已被正确透传进节点容器并被 ROCm 运行时识别，集群内的 GPU 能力验证通过。

深入学习 GPU 透传

GPU 透传本质上是把宿主机的 PCI/DRM 设备安全地暴露给虚拟机或容器。如果想要深入了解 PCI passthrough（尤其是基于 OVMF 的完整虚拟化透传方案），可以参考 ArchWiki 上关于 PCI passthrough via OVMF 的文档，其中覆盖了 IOMMU 分组、VFIO 绑定、ROM 与启动参数等更底层的细节。

为什么 Windows 上不支持 AMD GPU？

minikube 在 Windows 宿主机上主要通过 Hyper-V 或 VirtualBox 运行，而这两种虚拟化方案都难以实现 AMD GPU 透传：

• VirtualBox：其 PCI passthrough 功能不支持 Windows 宿主机，无法把物理 GPU 设备直通给客户机；
• Hyper-V：支持 DDA（离散设备分配，Discrete Device Assignment），但该能力仅面向 Windows Server 2016 及之后的服务器版本提供，而服务器操作系统并不是运行 minikube 的典型场景。

正因为在 Windows 上唯一可能的 GPU 支持路径落在用户通常不会运行 minikube 的服务器系统上，项目维护者没有投入精力去实现 Windows 上的 GPU 支持。因此，如果你需要在 Windows 上做 AMD GPU 相关的本地开发，当前可行的方式是使用 Linux 宿主机（原生或 WSL2 内的 Linux 环境）运行 docker 驱动模式。

小结

在 minikube 中启用 AMD GPU 的完整链路可以概括为：宿主机安装 AMD 驱动 →minikube start --driver docker --container-runtime docker --gpus amd透传/dev/kfd与/dev/dri设备并自动部署amd-gpu-device-pluginaddon → 设备插件向 kubelet 注册amd.com/gpu资源 → Pod 通过resources.limits申请 GPU 并运行 ROCm 工作负载。整个过程只需一条启动命令加一个验证 Job，配合本文梳理的源码实现（参数校验 start.go、设备透传 oci.go、设备插件清单 amd-gpu-device-plugin.yaml.tmpl），即可快速在本地搭建面向 ROCm 的 GPU 开发与测试环境。

【免费下载链接】minikubeRun Kubernetes locally项目地址: https://gitcode.com/gh_mirrors/mi/minikube