设备插件

Kubernetes 提供了一个设备插件框架，您可以使用它来向 Kubelet 公告系统硬件资源。

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

设备插件注册

Kubelet 导出一个 Registration gRPC 服务

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

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

• 其 Unix 套接字的名称。
• 它构建的 Device Plugin 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 设备名称的处理要求 DevicePluginCDIDevices 功能网关 对 kubelet 和 kube-apiserver 都是启用的。这是在 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 进行标识，该 ID 的值与设备插件 在向 kubelet 注册时 报告的值一致。

gRPC 服务通过 /var/lib/kubelet/pod-resources/kubelet.sock 上的 Unix 套接字提供。设备插件资源的监控代理可以作为守护进程或 DaemonSet 部署。规范目录 /var/lib/kubelet/pod-resources 需要特权访问，因此监控代理必须在特权安全上下文中运行。如果设备监控代理作为 DaemonSet 运行，则 /var/lib/kubelet/pod-resources 必须作为 卷 挂载在设备监控代理的 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;
}

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

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 设备的 通用设备插件
• 用于英特尔 GPU、FPGA、QAT、VPU、SGX、DSA、DLB 和 IAA 设备的 英特尔设备插件
• 用于硬件辅助虚拟化的 KubeVirt 设备插件
• 用于容器优化操作系统的 NVIDIA GPU 设备插件
• RDMA 设备插件
• SocketCAN 设备插件
• Solarflare 设备插件
• SR-IOV 网络设备插件
• 用于赛灵思 FPGA 设备的 赛灵思 FPGA 设备插件

下一步

• 了解使用设备插件 调度 GPU 资源
• 了解如何在节点上 宣传扩展资源
• 了解 拓扑管理器
• 阅读有关使用 硬件加速 TLS 摄入 与 Kubernetes 的内容