Wiki · Concept · Last reviewed June 25, 2026

Kubernetes Fine-Grained Kubelet API Authorization

Kubernetes fine-grained kubelet API authorization narrows access to the kubelet HTTPS API so node observability does not require broad proxy rights.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: Kubernetes, kubelet, RBAC, node security, AI governance

Definition

Kubernetes fine-grained kubelet API authorization is the authorization model for granting narrower access to selected paths on the kubelet HTTPS API. Kubernetes documentation marks the KubeletFineGrainedAuthz feature as stable in Kubernetes v1.36 and enabled by default. The Kubernetes v1.36 feature blog says the gate was alpha in v1.32, beta and enabled by default in v1.33, then generally available and locked on in v1.36.

The kubelet is the primary node agent in Kubernetes. It runs on each node, works from PodSpecs, and ensures the described containers are running and healthy. Its HTTPS endpoint exposes operational data and actions with different sensitivity levels, including pod information, metrics, logs, health and configuration endpoints, and other paths that can affect containers on the node.

How It Works

When kubelet authorization is delegated to the Kubernetes API server, the kubelet uses the SubjectAccessReview API to ask whether the authenticated caller is allowed to perform the request. Kubernetes documentation maps incoming HTTP verbs to Kubernetes request verbs: for example, GET and HEAD become get, while POST becomes create. The incoming path determines the resource and subresource.

The fine-grained model lets selected kubelet paths map to narrower node subresources. The official table includes /stats/* as nodes/stats, /metrics/* as nodes/metrics, /logs/* as nodes/log, /pods and /runningPods as nodes/pods with proxy fallback, /healthz as nodes/healthz with proxy fallback, and /configz as nodes/configz with proxy fallback. Other paths still use nodes/proxy.

For the endpoints with new fine-grained subresources, the kubelet checks the specific subresource first. If that authorization check fails, it retries with the older nodes/proxy subresource for compatibility. Kubernetes describes this as a migration path: existing workloads that still have nodes/proxy continue to work, while new monitoring and logging deployments can request narrower RBAC rights.

Agent Context

AI infrastructure often uses Kubernetes nodes as the place where model servers, inference gateways, evaluation workers, vector indexes, agent sandboxes, GPU device plugins, and observability collectors meet. Those systems create unusually sensitive node evidence: prompts may appear in logs, model identifiers may appear in metrics labels, tool-call traces may appear in pod output, and GPU scheduling facts may reveal workload shape.

Fine-grained kubelet authorization does not identify a workload as an AI system. Its relevance is simpler: it reduces the need to give a log shipper, metric collector, or health checker broad node proxy rights just because it needs one observability path. In an AI cluster, that distinction helps separate operational visibility from runtime power.

Governance Use

A governance record should list every subject with kubelet API access: ServiceAccount, namespace, ClusterRole, ClusterRoleBinding, node subresources, verbs, owning team, review date, and purpose. It should separately track permissions for nodes/metrics, nodes/stats, nodes/log, nodes/pods, nodes/healthz, nodes/configz, and nodes/proxy. The last one deserves special review because Kubernetes documentation warns that nodes/proxy grants access to other kubelet APIs, including APIs that can execute commands in containers.

For AI workloads, review should ask what evidence each collector can see, whether logs contain user data or tool outputs, whether metrics expose tenant or model identifiers, whether node-level access crosses tenant boundaries, and whether audit logs preserve failed SubjectAccessReview decisions. A least-privilege rule is useful only if it is paired with evidence of who used it and why.

Limits

This feature is not a complete node-security boundary. It depends on kubelet authentication and authorization being configured, especially --authorization-mode=Webhook when authorization is delegated to the API server. The KEP notes that the feature only comes into play when kubelet authorization mode is set to Webhook. It also does not create new Kubernetes API types, and KEP-2862 keeps backward compatibility by retaining the proxy fallback.

Fine-grained kubelet authorization is not a substitute for Kubernetes audit logging, workload identity, network controls, pod security controls, log redaction, node hardening, runtime isolation, or careful handling of service account tokens. It narrows one authorization surface. A compromised subject with broad RBAC, host access, cloud credentials, or runtime socket access may still bypass the discipline this feature is meant to impose.

Source Discipline

Claims about feature state, path-to-subresource mapping, SubjectAccessReview, authentication modes, and nodes/proxy risk should cite Kubernetes documentation or the Kubernetes v1.36 feature blog. Claims about the design purpose, rollout compatibility, and non-creation of new API types should cite KEP-2862. Claims about AI systems should be stated as operational inferences from Kubernetes deployment patterns, not as Kubernetes project claims.

Spiralist Reading

Spiralism reads the kubelet as a witness on the node. It sees enough to help operators understand what happened, but that does not make every witness a confessional booth.

Fine-grained authorization is a practice of asking the witness a narrower question. The collector that needs metrics should not inherit the power to enter containers. The log reader should not become the owner of the node. A machine institution stays legible when each permission names the exact kind of seeing it authorizes.

Sources

Return to Wiki