Docs update for Node Declared Features (KEP-5328) alpha

Author: pravk03

content/en/docs/concepts/scheduling-eviction/_index.md

@@ -25,6 +25,7 @@ of terminating one or more Pods on Nodes.
 * [Resource Bin Packing for Extended Resources](/docs/concepts/scheduling-eviction/resource-bin-packing/)
 * [Pod Scheduling Readiness](/docs/concepts/scheduling-eviction/pod-scheduling-readiness/)
 * [Descheduler](https://github.com/kubernetes-sigs/descheduler#descheduler-for-kubernetes)
+* [Node Declared Features](/docs/concepts/scheduling-eviction/node-declared-features/)
 
 ## Pod Disruption
 

content/en/docs/concepts/scheduling-eviction/node-declared-features.md

@@ -0,0 +1,53 @@
+---
+title: Node Declared Features
+weight: 160
+---
+
+{{< feature-state feature_gate_name="NodeDeclaredFeatures" >}}
+
+Kubernetes nodes use _declared features_ to report the availability of specific
+features that are new or feature-gated. Control plane components
+utilize this information to make better decisions. The kube-scheduler, via the
+`NodeDeclaredFeatures` plugin, ensures pods are only placed on nodes that
+explicitly support the features the pod requires. Additionally, the
+`NodeDeclaredFeatureValidator` admission controller validates pod updates
+against a node's declared features.
+
+This mechanism helps manage version skew and improve cluster stability,
+especially during cluster upgrades or in mixed-version environments where nodes
+might not all have the same features enabled. This is intended for Kubernetes
+feature developers introducing new node-level features and works in the
+background; application developers deploying Pods do not need to interact with
+this framework directly.
+
+## How it Works
+
+1.  **Kubelet Feature Reporting:** At startup, the kubelet on each node detects
+    which managed Kubernetes features are currently enabled and reports them
+    in the `.status.declaredFeatures` field of the Node. Only features
+    under active development are included in this field.
+2.  **Scheduler Filtering:** The default kube-scheduler uses the
+    `NodeDeclaredFeatures` plugin. This plugin:
+    * In the `PreFilter` stage, checks the `PodSpec` to infer the set of node
+      features required by the pod.
+    * In the `Filter` stage, checks if the features listed in the node's
+      `.status.declaredFeatures` satisfy the requirements inferred for the Pod.
+      Pods will not be scheduled on nodes lacking the required features.
+    Custom schedulers can also utilize the
+    `.status.declaredFeatures` field to enforce similar constraints.
+3.  **Admission Control:** The `nodedeclaredfeaturevalidator` admission controller
+    can reject Pods that require features not declared by the node they are
+    bound to, preventing issues during pod updates.
+
+## Enabling node declared features
+
+To use Node Declared Features, the `NodeDeclaredFeatures`
+[feature gate](/docs/reference/command-line-tools-reference/feature-gates/#NodeDeclaredFeatures)
+must be enabled on the `kube-apiserver`, `kube-scheduler`, and `kubelet`
+components.
+
+## {{% heading "whatsnext" %}}
+
+* Read the KEP for more details:
+    [KEP-5328: Node Declared Features](https://github.com/kubernetes/enhancements/blob/6d3210f7dd5d547c8f7f6a33af6a09eb45193cd7/keps/sig-node/5328-node-declared-features/README.md)
+* Read about the [`NodeDeclaredFeatureValidator` admission controller](/docs/reference/access-authn-authz/admission-controllers/#nodedeclaredfeaturevalidator).

content/en/docs/reference/access-authn-authz/admission-controllers.md

@@ -568,6 +568,23 @@ A `Namespace` deletion kicks off a sequence of operations that remove all object
 etc.) in that namespace.  In order to enforce integrity of that process, we strongly recommend
 running this admission controller.
 
+### NodeDeclaredFeatureValidator {#nodedeclaredfeaturevalidator}
+
+{{< feature-state feature_gate_name="NodeDeclaredFeatures" >}}
+
+**Type**: Validating.
+
+This admission controller intercepts writes to bound Pods, to ensure that the
+changes are compatible with the features declared by the node where the Pod is
+currently running. It uses the `.status.declaredFeatures` field of the Node to
+determine the set of enabled features. If a Pod update requires a feature that
+is not listed in the features of its current node, the admission controller
+will reject the update request. This prevents runtime failures due to feature
+mismatch after a Pod has been scheduled.
+
+This admission controller is enabled by
+default if the [`NodeDeclaredFeatures`](/docs/reference/command-line-tools-reference/feature-gates/#NodeDeclaredFeatures) feature gate is enabled.
+
 ### NodeRestriction {#noderestriction}
 
 **Type**: Validating.

content/en/docs/reference/command-line-tools-reference/feature-gates/NodeDeclaredFeatures.md

@@ -0,0 +1,15 @@
+---
+title: NodeDeclaredFeatures
+content_type: feature_gate
+_build:
+  list: never
+  render: false
+
+stages:
+  - stage: alpha
+    defaultValue: false
+    fromVersion: "1.35"
+---
+Enables Nodes to report supported features via their `.status`. This enables the 
+scheduler and admission controller to prevent operations on nodes lacking features
+required by the pod. See [Node Declared Features](/docs/concepts/scheduling-eviction/node-declared-features/).

content/en/docs/reference/node/node-status.md

@@ -17,6 +17,7 @@ A Node's status contains the following information:
 * [Conditions](#condition)
 * [Capacity and Allocatable](#capacity)
 * [Info](#info)
+* [Declared Features](#declaredfeatures)
 
 You can use `kubectl` to view a Node's status and other details:
 
@@ -109,6 +110,23 @@ operating system the node uses.
 The kubelet gathers this information from the node and publishes it into
 the Kubernetes API.
 
+## Declared features {#declaredfeatures}
+
+{{< feature-state feature_gate_name="NodeDeclaredFeatures" >}}
+
+This field lists specific Kubernetes features that are currently enabled on the
+node's kubelet via [feature gates](/docs/reference/command-line-tools-reference/feature-gates/).
+The features are reported by the kubelet as a list of strings in the
+`.status.declaredFeatures` field of the Node object.
+
+This field is intended for newer features under active development; features that
+have graduated and no longer require a feature gate are considered baseline and
+are not declared in this field. This reflects the enablement of Kubernetes
+features, not the underlying operating system or kernel capabilities of the node.
+
+See [Node Declared Features](/docs/concepts/scheduling-eviction/node-declared-features/)
+for more details.
+
 ## Heartbeats
 
 Heartbeats, sent by Kubernetes nodes, help your cluster determine the