Pod 级资源管理器参考

Pod 级资源管理器参考

特性状态： Beta since Kubernetes v1.37; （默认禁用）
More information about this feature

To use this feature, you (or a cluster administrator) will need to enable the PodLevelResourceManagers feature gate for all relevant components in your cluster.

See Enable Or Disable Feature Gates for more information.

本文档提供 kubelet 中 Pod 级资源管理器实现的参考细节， 包括 PodResources API 的报告结构， 以及版本升级和降级期间状态检查点格式的迁移。

PodResources API

在 Kubernetes 1.37 中，当 PodLevelResourceManagers 特性门控启用时， kubelet 的节点本地 PodResources gRPC API 会原生包含 Pod 级资源条目。 这使节点本地的监控代理和设备插件可以查询分配给某个 Pod 的独占资源：

  • Pod 级字段： PodResources gRPC 消息包含顶层 cpu_ids 和 memory 字段， 用于表示分配给整个 Pod 的独占 CPU 和 NUMA 对齐的内存块。
  • 容器级过滤： 容器级报告可避免重复计算：
    • 获得单独独占分配的容器会在 ContainerResources 中报告其被分配到的具体 CPU 和内存。
    • 在 Pod 预算内共享资源的容器（运行于 Pod 隔离的共享池或节点共享池中） 会把容器级的 cpu_ids 和 memory 字段留空，该分配则反映在 Pod 级。
  • 计算 Pod 共享池： API 消费者可以用 Pod 级分配减去所有容器级独占分配的并集，从而算出 Pod 级共享池中的资源： PodSharedPool.CpuIds = Pod.CpuIds - Union(all Container.CpuIds)

以下是当指定了 Pod 级资源时 PodResources API 报告行为的摘要：

1. 拓扑管理器范围：pod

拓扑管理器会分配一个 Pod 级的资源预算。PodResources 中的 Pod 级字段会填入这一分配。

`pod` 范围下 PodResources API 的报告行为
容器组合Pod 级 cpu_ids / memory容器级 cpu_ids / memory详情 / 说明
独占容器（Guaranteed）填入完整的 Pod 级分配。填入该容器分配得到的子集。该容器获得从 Pod 级分配中划分出的独占 CPU。
共享池容器填入完整的 Pod 级分配。空因为该容器运行在 Pod 共享池中，所以可避免重复计算。

2. 拓扑管理器范围：container

kubelet 会按容器逐个评估资源分配。Pod 级的 PodResources API 字段保持为空。

`container` 范围下 PodResources API 的报告行为
容器组合Pod 级 cpu_ids / memory容器级 cpu_ids / memory详情/说明
独占容器（Guaranteed）空填入该容器分配得到的 CPU/内存。该容器直接从节点的可分配池中获得独占分配。
共享池容器空空运行在节点的常规共享池中。

kubelet 状态检查点格式

kubelet 维护本地状态检查点文件（位于 kubelet 根目录中的 cpu_manager_state 和 memory_manager_state）， 以便在 kubelet 版本升级和降级期间的重启过程中保留资源分配。

Kubernetes v1.36 中的检查点格式

在 Kubernetes v1.36 中，启用 PodLevelResourceManagers 特性门控会使用内部的 V3 格式保存状态检查点。虽然升级到 1.36 是向后兼容的， 但 V3 格式缺少前向兼容性。如果你把 1.36 的 kubelet 降级到 1.35 或更早版本 （或者在 1.36 中活跃使用之后禁用该特性门控），较旧的 kubelet 无法解析 V3 检查点， 并会因 checkpoint is corrupted 错误而启动失败。

要恢复，请腾空该节点，手动删除检查点文件 （cpu_manager_state 和 memory_manager_state），然后重启 kubelet。

Kubernetes v1.37 及更高版本中的前向兼容格式

在 Kubernetes v1.37 中，检查点文件使用一种通用的 V4 格式， 其中内嵌标准的 V2 结构。这引入了一种前向兼容的内部格式， 使检查点不兼容成为一次性问题，而不是你在未来更新中预期会遇到的情况：

  • 升级与降级兼容性： 较旧的 kubelet 版本可以读取 V4 检查点而不会出现损坏错误。 如果你把 v1.37 的 kubelet 降级到 v1.36（即使在 1.36 中启用了 PodLevelResourceManagers），1.36 的 kubelet 也能从 V2 安全地恢复标准容器分配。
  • Pod 级条目的丢失： 虽然 kubelet 可以安全启动而不会出现损坏， 但在降级到 v1.36 时，活跃的 Pod 级资源分配（PodEntries）会丢失。

如果你运行的不是 Kubernetes v1.37，请查阅该版本 Kubernetes 的文档，了解升级和降级相关的信息。

另请参阅

  • Pod 级资源管理器概念： 阅读该概念页面，了解整体架构、QoS 类要求， 以及 pod 和 container 范围下的资源管理器分配规则。
  • kubelet 状态文件参考： 进一步了解本地状态检查点文件（cpu_manager_state 和 memory_manager_state）存放在宿主机文件系统的什么位置。
最后修改 September 29, 2026 at 10:54 AM PST: [zh] Add pod-level-resource-managers.md (a687e1baf0)