设备插件

Kubernetes 提供了一个设备插件框架，你可以使用该框架将系统硬件资源通告给 Kubelet。

供应商可以实现一个设备插件，然后你可以手动部署该插件或将其部署为 DaemonSet，而不是自定义 Kubernetes 本身的代码。 目标设备包括 GPU、高性能 NIC、FPGA、InfiniBand 适配器和其他类似的计算资源，这些资源可能需要特定于供应商的初始化和设置。

设备插件注册

kubelet 导出一个 Registration gRPC 服务

service Registration {
	rpc Register(RegisterRequest) returns (Empty) {}
}

设备插件可以通过此 gRPC 服务向 kubelet 注册自身。 在注册期间，设备插件需要发送

• 其 Unix 套接字的名称。
• 它构建所依据的设备插件 API 版本。
• 它要通告的 ResourceName。 此处的 ResourceName 需要遵循 扩展资源命名方案，如 vendor-domain/resourcetype。（例如，NVIDIA GPU 通告为 nvidia.com/gpu。）

成功注册后，设备插件会向 kubelet 发送其管理的设备列表，然后 kubelet 负责将这些资源作为 kubelet 节点状态更新的一部分通告给 API 服务器。 例如，在设备插件使用 kubelet 注册 hardware-vendor.example/foo 并在节点上报告两个运行正常的设备后，节点状态会更新以通告该节点已安装并可使用 2 个“Foo”设备。

然后，用户可以在 Pod 规范中请求设备（请参阅container）。 请求扩展资源类似于你管理其他资源的请求和限制的方式，但存在以下差异

• 扩展资源仅支持作为整数资源，并且不能过度分配。
• 设备不能在容器之间共享。

示例

假设 Kubernetes 集群正在运行一个设备插件，该插件在某些节点上通告资源 hardware-vendor.example/foo。 以下是一个 Pod 请求此资源以运行演示工作负载的示例

---
apiVersion: v1
kind: Pod
metadata:
  name: demo-pod
spec:
  containers:
    - name: demo-container-1
      image: registry.k8s.io/pause:2.0
      resources:
        limits:
          hardware-vendor.example/foo: 2
#
# This Pod needs 2 of the hardware-vendor.example/foo devices
# and can only schedule onto a Node that's able to satisfy
# that need.
#
# If the Node has more than 2 of those devices available, the
# remainder would be available for other Pods to use.

设备插件实现

设备插件的常规工作流程包括以下步骤

1. 初始化。在此阶段，设备插件执行特定于供应商的初始化和设置，以确保设备处于就绪状态。

2. 插件启动一个 gRPC 服务，该服务在主机路径 /var/lib/kubelet/device-plugins/ 下使用 Unix 套接字，并实现以下接口

   service DevicePlugin {
         // GetDevicePluginOptions returns options to be communicated with Device Manager.
         rpc GetDevicePluginOptions(Empty) returns (DevicePluginOptions) {}
   
         // ListAndWatch returns a stream of List of Devices
         // Whenever a Device state change or a Device disappears, ListAndWatch
         // returns the new list
         rpc ListAndWatch(Empty) returns (stream ListAndWatchResponse) {}
   
         // Allocate is called during container creation so that the Device
         // Plugin can run device specific operations and instruct Kubelet
         // of the steps to make the Device available in the container
         rpc Allocate(AllocateRequest) returns (AllocateResponse) {}
   
         // GetPreferredAllocation returns a preferred set of devices to allocate
         // from a list of available ones. The resulting preferred allocation is not
         // guaranteed to be the allocation ultimately performed by the
         // devicemanager. It is only designed to help the devicemanager make a more
         // informed allocation decision when possible.
         rpc GetPreferredAllocation(PreferredAllocationRequest) returns (PreferredAllocationResponse) {}
   
         // PreStartContainer is called, if indicated by Device Plugin during registration phase,
         // before each container start. Device plugin can run device specific operations
         // such as resetting the device before making devices available to the container.
         rpc PreStartContainer(PreStartContainerRequest) returns (PreStartContainerResponse) {}
   }
   

   注意

   不需要插件为 GetPreferredAllocation() 或 PreStartContainer() 提供有用的实现。 如果有，则应在调用 GetDevicePluginOptions() 发回的 DevicePluginOptions 消息中设置指示这些调用是否可用的标志。 kubelet 将始终调用 GetDevicePluginOptions() 以查看哪些可选函数可用，然后再直接调用任何函数。

3. 插件通过主机路径 /var/lib/kubelet/device-plugins/kubelet.sock 上的 Unix 套接字向 kubelet 注册自身。

   注意

   工作流程的顺序很重要。 插件必须在向 kubelet 注册自身之前启动 gRPC 服务，才能成功注册。

4. 成功注册后，设备插件以服务模式运行，在此期间，它会持续监视设备运行状况，并在任何设备状态更改时向 kubelet 报告。 它还负责处理 Allocate gRPC 请求。 在 Allocate 期间，设备插件可以执行特定于设备的操作；例如，GPU 清理或 QRNG 初始化。 如果操作成功，则设备插件会返回一个 AllocateResponse，其中包含用于访问已分配设备的容器运行时配置。 kubelet 将此信息传递给容器运行时。

   一个 AllocateResponse 包含零个或多个 ContainerAllocateResponse 对象。 在这些对象中，设备插件定义必须对容器的定义进行的修改，以提供对设备的访问。 这些修改包括

   • 注解
   • 设备节点
   • 环境变量
   • 挂载
   • 完全限定的 CDI 设备名称

   注意

   设备管理器处理完全限定的 CDI 设备名称需要为 kubelet 和 kube-apiserver 启用 DevicePluginCDIDevices 特性门控。 此功能在 Kubernetes v1.28 中作为 alpha 功能添加，在 v1.29 中升级到 beta 版，在 v1.31 中升级到 GA。

处理 kubelet 重启

设备插件应检测 kubelet 重启并向新的 kubelet 实例重新注册自身。 新的 kubelet 实例会在启动时删除 /var/lib/kubelet/device-plugins 下的所有现有 Unix 套接字。 设备插件可以监视其 Unix 套接字的删除，并在发生此类事件时重新注册自身。

设备插件和不健康的设备

在某些情况下，设备会发生故障或关闭。 在这种情况下，设备插件的责任是使用 ListAndWatchResponse API 将情况通知给 kubelet。

一旦设备被标记为不健康，kubelet 将减少节点上此资源的可分配计数，以反映有多少设备可用于调度新的 Pod。 资源的容量计数不会改变。

分配给故障设备的 Pod 将继续分配给此设备。 通常，依赖于设备的代码将开始失败，并且如果 Pod 的 restartPolicy 不是 Always，则 Pod 可能会进入失败阶段，否则会进入崩溃循环。

在 Kubernetes v1.31 之前，要了解 Pod 是否与故障设备关联，方法是使用 PodResources API。

通过启用特性门控 ResourceHealthStatus，allocatedResourcesStatus 字段将添加到每个容器状态中，在每个 Pod 的 .status 中。 allocatedResourcesStatus 字段报告分配给每个容器的设备的运行状况信息。

对于失败的 Pod，或者在你怀疑发生故障的情况下，你可以使用此状态来了解 Pod 行为是否可能与设备故障相关联。 例如，如果加速器报告过热事件，则 allocatedResourcesStatus 字段可能能够报告此情况。

设备插件部署

你可以将设备插件作为 DaemonSet、节点操作系统的软件包或手动部署。

规范目录 /var/lib/kubelet/device-plugins 需要特权访问，因此设备插件必须在特权安全上下文中运行。 如果你将设备插件部署为 DaemonSet，则必须将 /var/lib/kubelet/device-plugins 作为插件的 卷挂载在插件的 PodSpec 中。

如果你选择 DaemonSet 方法，则可以依赖 Kubernetes 来：将设备插件的 Pod 放置到节点上，在失败后重新启动守护程序 Pod，并帮助实现升级自动化。

API 兼容性

以前，版本控制方案要求设备插件的 API 版本与 Kubelet 的版本完全匹配。 自从此功能在 v1.12 中升级到 Beta 版以来，这不再是一个硬性要求。 API 已进行版本控制，并且自此功能的 Beta 版升级以来一直保持稳定。 因此，kubelet 升级应该是无缝的，但仍然可能在稳定之前 API 中出现更改，从而无法保证升级是非中断性的。

作为一个项目，Kubernetes 建议设备插件开发人员

• 注意未来版本中的设备插件 API 更改。
• 支持多个版本的设备插件 API，以实现向后/向前兼容性。

若要在需要升级到具有较新设备插件 API 版本的 Kubernetes 版本的节点上运行设备插件，请在升级这些节点之前升级你的设备插件以支持这两个版本。 采取这种方法将确保在升级期间设备分配的持续运行。

监视设备插件资源

为了监控设备插件提供的资源，监控代理需要能够发现节点上正在使用的设备集，并获取元数据来描述该指标应与哪个容器关联。设备监控代理公开的 Prometheus 指标应遵循 Kubernetes 仪表化指南，使用 pod、namespace 和 container Prometheus 标签来标识容器。

kubelet 提供了一个 gRPC 服务，以支持发现正在使用的设备，并为这些设备提供元数据。

// PodResourcesLister is a service provided by the kubelet that provides information about the
// node resources consumed by pods and containers on the node
service PodResourcesLister {
    rpc List(ListPodResourcesRequest) returns (ListPodResourcesResponse) {}
    rpc GetAllocatableResources(AllocatableResourcesRequest) returns (AllocatableResourcesResponse) {}
    rpc Get(GetPodResourcesRequest) returns (GetPodResourcesResponse) {}
}

List gRPC 端点

List 端点提供有关正在运行的 Pod 的资源信息，包括独占分配的 CPU 的 ID、设备插件报告的设备 ID 以及这些设备分配到的 NUMA 节点的 ID。此外，对于基于 NUMA 的机器，它还包含有关为容器预留的内存和巨页的信息。

从 Kubernetes v1.27 开始，List 端点可以提供有关通过 DynamicResourceAllocation API 在 ResourceClaims 中分配的正在运行的 Pod 的资源信息。要启用此功能，必须使用以下标志启动 kubelet

--feature-gates=DynamicResourceAllocation=true,KubeletPodResourcesDynamicResources=true

// ListPodResourcesResponse is the response returned by List function
message ListPodResourcesResponse {
    repeated PodResources pod_resources = 1;
}

// PodResources contains information about the node resources assigned to a pod
message PodResources {
    string name = 1;
    string namespace = 2;
    repeated ContainerResources containers = 3;
}

// ContainerResources contains information about the resources assigned to a container
message ContainerResources {
    string name = 1;
    repeated ContainerDevices devices = 2;
    repeated int64 cpu_ids = 3;
    repeated ContainerMemory memory = 4;
    repeated DynamicResource dynamic_resources = 5;
}

// ContainerMemory contains information about memory and hugepages assigned to a container
message ContainerMemory {
    string memory_type = 1;
    uint64 size = 2;
    TopologyInfo topology = 3;
}

// Topology describes hardware topology of the resource
message TopologyInfo {
        repeated NUMANode nodes = 1;
}

// NUMA representation of NUMA node
message NUMANode {
        int64 ID = 1;
}

// ContainerDevices contains information about the devices assigned to a container
message ContainerDevices {
    string resource_name = 1;
    repeated string device_ids = 2;
    TopologyInfo topology = 3;
}

// DynamicResource contains information about the devices assigned to a container by Dynamic Resource Allocation
message DynamicResource {
    string class_name = 1;
    string claim_name = 2;
    string claim_namespace = 3;
    repeated ClaimResource claim_resources = 4;
}

// ClaimResource contains per-plugin resource information
message ClaimResource {
    repeated CDIDevice cdi_devices = 1 [(gogoproto.customname) = "CDIDevices"];
}

// CDIDevice specifies a CDI device information
message CDIDevice {
    // Fully qualified CDI device name
    // for example: vendor.com/gpu=gpudevice1
    // see more details in the CDI specification:
    // https://github.com/container-orchestrated-devices/container-device-interface/blob/main/SPEC.md
    string name = 1;
}

GetAllocatableResources gRPC 端点

GetAllocatableResources 提供有关工作节点上初始可用资源的信息。它提供的信息比 kubelet 导出到 APIServer 的信息更多。

// AllocatableResourcesResponses contains information about all the devices known by the kubelet
message AllocatableResourcesResponse {
    repeated ContainerDevices devices = 1;
    repeated int64 cpu_ids = 2;
    repeated ContainerMemory memory = 3;
}

ContainerDevices 确实会公开拓扑信息，声明设备与哪些 NUMA 单元相关联。NUMA 单元使用一个不透明的整数 ID 来标识，该值与设备插件在向 kubelet 注册自身时报告的值一致。

gRPC 服务通过 unix 套接字在 /var/lib/kubelet/pod-resources/kubelet.sock 上提供。设备插件资源的监控代理可以部署为守护进程或 DaemonSet。规范目录 /var/lib/kubelet/pod-resources 需要特权访问，因此监控代理必须在特权安全上下文中运行。如果设备监控代理作为 DaemonSet 运行，则必须将 /var/lib/kubelet/pod-resources 作为设备监控代理的 Volume 安装在其 PodSpec 中。

Get gRPC 端点

Get 端点提供有关正在运行的 Pod 的资源信息。它公开的信息与 List 端点中描述的信息类似。Get 端点需要正在运行的 Pod 的 PodName 和 PodNamespace。

// GetPodResourcesRequest contains information about the pod
message GetPodResourcesRequest {
    string pod_name = 1;
    string pod_namespace = 2;
}

要启用此功能，您必须使用以下标志启动 kubelet 服务

--feature-gates=KubeletPodResourcesGet=true

Get 端点可以提供与动态资源分配 API 分配的动态资源相关的 Pod 信息。要启用此功能，您必须确保您的 kubelet 服务使用以下标志启动

--feature-gates=KubeletPodResourcesGet=true,DynamicResourceAllocation=true,KubeletPodResourcesDynamicResources=true

设备插件与拓扑管理器集成

拓扑管理器是 Kubelet 组件，允许以拓扑对齐的方式协调资源。为此，扩展了设备插件 API 以包含 TopologyInfo 结构。

message TopologyInfo {
    repeated NUMANode nodes = 1;
}

message NUMANode {
    int64 ID = 1;
}

希望利用拓扑管理器的设备插件可以将填充的 TopologyInfo 结构作为设备注册的一部分返回，同时返回设备 ID 和设备的健康状况。然后，设备管理器将使用此信息来咨询拓扑管理器并做出资源分配决策。

TopologyInfo 支持将 nodes 字段设置为 nil 或 NUMA 节点列表。这允许设备插件通告跨越多个 NUMA 节点的设备。

将 TopologyInfo 设置为 nil 或为给定设备提供一个空的 NUMA 节点列表表示设备插件没有该设备的 NUMA 亲和性偏好。

由设备插件为设备填充的 TopologyInfo 结构的示例

pluginapi.Device{ID: "25102017", Health: pluginapi.Healthy, Topology:&pluginapi.TopologyInfo{Nodes: []*pluginapi.NUMANode{&pluginapi.NUMANode{ID: 0,},}}}

设备插件示例

以下是一些设备插件实现的示例

• Akri，可让您轻松公开异构叶设备（例如 IP 摄像头和 USB 设备）。
• AMD GPU 设备插件
• 用于通用 Linux 设备和 USB 设备的通用设备插件
• 用于异构 AI 计算虚拟化中间件（例如，NVIDIA、Cambricon、Hygon、Iluvatar、MThreads、Ascend、Metax）的 HAMi
• 用于 Intel GPU、FPGA、QAT、VPU、SGX、DSA、DLB 和 IAA 设备的 Intel 设备插件
• 用于硬件辅助虚拟化的 KubeVirt 设备插件
• NVIDIA GPU 设备插件，NVIDIA 用于公开 NVIDIA GPU 和监控 GPU 健康状况的官方设备插件
• 用于容器优化操作系统的 NVIDIA GPU 设备插件
• RDMA 设备插件
• SocketCAN 设备插件
• Solarflare 设备插件
• SR-IOV 网络设备插件
• 用于 Xilinx FPGA 设备的 Xilinx FPGA 设备插件

下一步

• 了解如何使用设备插件调度 GPU 资源
• 了解如何在节点上通告扩展资源
• 了解拓扑管理器
• 阅读有关在 Kubernetes 中使用硬件加速 TLS 入口的信息