Kubelet Pod Info gRPC API

特性状态: Kubernetes v1.35 [alpha](默认禁用)

Kubelet Pod Info gRPC API 为节点本地组件提供了一种直接从 kubelet 查询节点上运行的 Pod 信息的方法。 这通过移除对 Kubernetes API 服务器的节点本地信息依赖来提高可靠性,并减少控制平面的负载。

通过 UNIX 套接字上的文件权限,该 API 的访问权限被限制为本地管理员用户(通常为 root)。

端点

API 在以下 UNIX 套接字上监听: /var/lib/kubelet/pods/kubelet.sock

说明:

此 API 在 Windows 节点上不受支持。

操作

API 提供以下 gRPC 方法:

ListPods

返回 kubelet 在节点上当前管理的所有 Pod 列表。

WatchPods

返回 Pod 更新流。每当 Pod 的状态在本地发生变化时,kubelet 会通过该流发送更新后的 Pod 信息。

GetPod

返回由 UID 标识的特定 Pod 的信息。

API 定义

API 使用以下 protobuf 定义:

import "google/protobuf/field_mask.proto";
import "k8s.io/api/core/v1/generated.proto";

service Pods {
    // ListPods 返回 v1.Pod 列表,可选地按字段掩码过滤。
    rpc ListPods(PodListRequest) returns (PodListResponse) {}
    // WatchPods 返回 Pod 更新流,可选地按字段掩码过滤。
    rpc WatchPods(PodWatchRequest) returns (stream PodWatchResponse) {}
    // GetPod 返回给定 Pod UID 的 v1.Pod,可选地按字段掩码过滤。
    rpc GetPod(PodGetRequest) returns (PodGetResponse) {}
}

message PodListRequest {
    // gRPC 元数据中的可选字段掩码,用于指定要返回的 Pod 字段。
}

message PodListResponse {
    repeated v1.Pod pods = 1;
}

message PodWatchRequest {
    // gRPC 元数据中的可选字段掩码,用于指定要返回的 Pod 字段。
}

message PodWatchResponse {
    v1.Pod pod = 1;
}

message PodGetRequest {
    string podUID = 1;
    // gRPC 元数据中的可选字段掩码,用于指定要返回的 Pod 字段。
}

message PodGetResponse {
    v1.Pod pod = 1;
}

字段选择

API 支持 google.protobuf.FieldMask,允许客户端仅请求他们需要的特定字段(例如 status.phasestatus.podIPs)。 这实现了精简和高效的数据传输。如果未提供字段掩码,则返回完整的 v1.Pod 对象。

可靠性和可用性

API 提供 kubelet 本地已知的最新的信息,这些信息来自其内部缓存以及与容器运行时的协调。 即使节点失去与 Kubernetes 控制平面的连接,该 API 仍然可用。

如果 kubelet 最近重启且其内部状态尚未完全初始化,API 会返回 gRPC FAILED_PRECONDITION 错误。


最后修改 April 25, 2026 at 8:38 PM PST: [zh-cn]Add kubelet-pod-info-grpc-api (87650f18fd)