Kubernetes v1.37 Unveils Node Lifecycle Conditions: A Guide for Operators

Before Kubernetes v1.37 there was no Kubernetes‑owned field that could convey a single, authoritative view of a node’s operational phase. Controllers had to infer state from a mix of Ready status, taints, Pod termination, custom annotations, or external scripts. This fragmented approach caused inconsistent decisions: a DaemonSet controller could replace a pod that the kubelet was terminating for a graceful shutdown, while a Job controller might wait forever for a pod that an administrator was deliberately draining. The absence of a shared signal therefore increased coordination complexity and risk of conflicting actions across the scheduler, autoscalers, storage operators, and external maintenance systems.

Five Node Lifecycle Conditions introduced in v1.37

• DrainInProgress – The node is actively being drained according to the administrator‑defined criteria (e.g., pod eviction thresholds).
• Drained – The node has satisfied the chosen drain criteria; no further eviction is required.
• MaintenancePlanned – A future maintenance window is scheduled for the node (hardware replacement, software rollout, etc.).
• MaintenanceInProgress – The node is currently undergoing the planned maintenance activity.
• GracefulNodeShutdownInProgress – The node is executing a graceful shutdown sequence as defined by the kubelet.

Each condition follows the standard NodeCondition schema: status can be True, False, or Unknown; reason supplies a stable, machine‑readable code; and message offers a human‑readable explanation. Example of publishing a planned maintenance condition:

status:
  conditions:
  - type: MaintenancePlanned
    status: "True"
    reason: MaintenanceWindow
    lastTransitionTime: "2026-12-09T12:00:00Z"
    message: "Hardware maintenance is scheduled for this Node"

Practical usage patterns:

1. Automation schedules a MaintenancePlanned condition weeks in advance.
2. When the window opens, the controller flips MaintenanceInProgress to True and, if necessary, sets DrainInProgress.
3. After eviction criteria are satisfied, the controller marks Drained as True and clears DrainInProgress.
4. During a live kernel patch that does not require pod eviction, only MaintenanceInProgress is set, leaving the drain flags untouched.
5. When a node receives a shutdown signal, the kubelet sets GracefulNodeShutdownInProgress, allowing workloads to observe and react appropriately.

By providing a single, authoritative source of truth, these conditions enable dashboards, alerting pipelines, and future core controllers to make lifecycle‑aware decisions without re‑inventing inference logic. This shared signal is the foundation for more deterministic node‑level operations across the Kubernetes ecosystem.

Kubernetes v1.37 reserves five well‑known NodeConditionType constants—DrainInProgress, Drained, MaintenancePlanned, MaintenanceInProgress, and GracefulNodeShutdownInProgress. By registering these names in the core API, the API server guarantees that any future component can reference the same string identifiers without risk of collision with custom conditions. The constants are defined in the same package that holds existing conditions such as Ready, ensuring they appear in kubectl get nodes -o yaml output and can be queried with standard field selectors.

The release also introduces the Alpha NodeLifecycleConditions feature gate. As an Alpha gate, it is disabled by default and currently behaves as a no‑op: it does not enforce ownership, validation, or read‑only semantics for the new conditions. The gate exists solely to provide a switch for the “opt‑in” behavior that will be added in later releases, when core controllers begin to consume the conditions. Because the gate is off, administrators may set the conditions immediately without any additional cluster configuration.

At this stage no core workload controller—scheduler, kubelet, DaemonSet controller, or autoscaler—interprets the new conditions. The absence of built‑in consumers means the conditions are a pure status channel; they are safe to publish today and will not affect pod scheduling, eviction, or node health calculations until future releases add explicit handling.

• Identify the component that owns a condition (e.g., a maintenance automation service owns MaintenancePlanned).
• Use the kubectl patch node command or the Node API to set the condition with status: "True", a stable reason, and a human‑readable message.
• Clear the condition by setting status: "False" or by removing the entry entirely once the lifecycle state ends.

apiVersion: v1
kind: Node
metadata:
  name: worker-01
status:
  conditions:
  - type: MaintenancePlanned
    status: "True"
    reason: MaintenanceWindow
    message: "Hardware maintenance scheduled for 02:00 UTC"
    lastTransitionTime: "2026-12-09T12:00:00Z"

By publishing these conditions now, administrators gain a shared, machine‑readable signal that can be consumed by dashboards, alerting pipelines, or custom controllers, while the core platform continues to operate unchanged.

Node lifecycle conditions introduced in Kubernetes v1.37 give a single, Kubernetes‑owned place to publish the state of a node while it is being drained, maintained, or gracefully shut down. Each condition (DrainInProgress, Drained, MaintenancePlanned, MaintenanceInProgress, GracefulNodeShutdownInProgress) follows the standard status/reason/message schema: True when the observation is active, False when it is not, and Unknown when the controller cannot determine the state.

Operational patterns

• Set‑once, clear‑once: an authorized controller writes the condition with status: True at the start of the operation and later either sets status: False or removes the entry when the operation completes.
• Stable reason values: use a short, machine‑readable token (e.g., MaintenanceWindow, EvictionStarted, GracefulShutdown) so downstream automation can match on it without parsing free‑form text.
• Human‑readable messages: include context such as the expected finish time, affected services, or remediation steps. This aids operators and alert dashboards.
• Ownership discipline: assign a single component (e.g., a maintenance controller, a drain script, or the kubelet) to own each condition to avoid conflicting writes.

Example workflows

Maintenance automation

apiVersion: v1
kind: Node
metadata:
  name: worker-01
status:
  conditions:
  - type: MaintenancePlanned
    status: "True"
    reason: MaintenanceWindow
    message: "Hardware replacement scheduled for 02:00 UTC"
  - type: MaintenanceInProgress
    status: "True"
    reason: FirmwareUpdate
    message: "Applying firmware version 5.12"

When the window opens, the controller flips MaintenancePlanned to False (or removes it) and sets MaintenanceInProgress to True. After the work finishes, MaintenanceInProgress is cleared.

Drain automation

# Begin drain
kubectl cordon worker-02
# Automation sets condition
kubectl patch node worker-02 -p '{"status":{"conditions":[{"type":"DrainInProgress","status":"True","reason":"EvictionStarted","message":"Evicting pods per policy"}]}}' --type=merge
# After criteria met
kubectl patch node worker-02 -p '{"status":{"conditions":[{"type":"DrainInProgress","status":"False"},{"type":"Drained","status":"True","reason":"CriteriaMet","message":"All pods evicted"}]}}' --type=merge

Graceful shutdown

apiVersion: v1
kind: Node
metadata:
  name: worker-03
status:
  conditions:
  - type: GracefulNodeShutdownInProgress
    status: "True"
    reason: PowerCycle
    message: "Node is shutting down after completing pod termination"

Guidance on status values

• True – the lifecycle phase is actively occurring.
• False – the phase has completed or is not applicable; clearing the condition is also acceptable.
• Unknown – use only when the controller cannot reliably detect the state (e.g., loss of node heartbeat).

By consistently applying these patterns, operators gain a reliable signal for dashboards, alerts, and downstream controllers (such as DaemonSet rollouts or storage operators) without altering existing scheduling or eviction mechanisms.

Kubernetes components must understand why a node is unavailable before they can act safely. Today each controller derives that understanding from a different subset of the node’s metadata:

• Readiness – indicates whether the kubelet reports the node as healthy, but does not distinguish failure from planned shutdown.
• Taints – influence scheduling and eviction, yet they do not attest that a drain is actively running or that maintenance has been scheduled.
• Pod phase – termination or “Terminating” states hint at a drain, but they provide no guarantee that the drain criteria have been satisfied.
• Labels/annotations – often added by cloud providers or custom scripts, these are informal and may be interpreted inconsistently.

Because the signals are fragmented, independently correct controllers can make contradictory decisions. For example, a DaemonSet controller may attempt to recreate a pod that the kubelet has already stopped during a graceful shutdown, while a Job controller may wait indefinitely for a pod to reach Succeeded on a node that an administrator is actively removing. A storage operator that learns of maintenance only after a drain has begun may miss the window to relocate volumes, leading to I/O errors.

The introduction of the five well‑known Node lifecycle conditions—DrainInProgress, Drained, MaintenancePlanned, MaintenanceInProgress, and GracefulNodeShutdownInProgress—provides a single, Kubernetes‑owned source of truth. Each condition carries a status (True, False, Unknown), a stable reason, and an optional human‑readable message. This structured metadata allows any component to query a node’s exact lifecycle phase without interpreting unrelated signals.

Practical impact:

• A scheduler can skip nodes with MaintenanceInProgress=True, preventing new pods from landing on a node that will soon be offline.
• The DaemonSet controller can treat DrainInProgress=True as a signal to pause rollout accounting, avoiding false‑negative availability metrics.
• Autoscalers can defer scale‑down actions while GracefulNodeShutdownInProgress=True, ensuring that graceful termination completes before resources are reclaimed.

By consolidating node state into these authoritative conditions, the cluster eliminates the need for each controller to infer intent from disparate cues, reducing the likelihood of conflicting actions and improving overall reliability.

The longer‑term vision for a lifecycle‑aware Kubernetes platform builds on the Node lifecycle conditions introduced in v1.37 (DrainInProgress, Drained, MaintenancePlanned, MaintenanceInProgress, GracefulNodeShutdownInProgress). These well‑known NodeConditionType constants provide a single, Kubernetes‑owned status field that can be read by any controller, reducing the need for each component to infer node state from disparate signals such as readiness, taints, or pod termination.

Future work, tracked in KEP‑5683, aims to move the conditions from an informational signal to an actionable contract. Expected enhancements include:

• Controller integration: The DaemonSet controller will consider MaintenanceInProgress when calculating rollout availability, preventing a node under maintenance from counting against the availability budget.
• Graceful shutdown coordination: The kubelet and node lifecycle controller will set GracefulNodeShutdownInProgress early in the shutdown sequence, allowing workload controllers (e.g., Jobs, StatefulSets) to pause new work and expedite pod termination.
• Explicit ownership and locking: A dedicated API may be added to let a single component claim a lifecycle condition, avoiding conflicting writes from multiple automation tools.
• Policy‑driven automation: Autoscalers and storage operators can react to MaintenancePlanned by pre‑emptively scaling resources or relocating data before the maintenance window begins.

Practically, an administrator can publish a maintenance window with the following manifest snippet, which will be visible to dashboards, alerts, and any controller that adopts the contract:

apiVersion: v1
kind: Node
metadata:
  name: worker-01
status:
  conditions:
  - type: MaintenancePlanned
    status: "True"
    reason: MaintenanceWindow
    message: "Hardware replacement scheduled for this node"

Engineers who want to influence these upcoming behaviors should engage with the community:

• Join the Node Lifecycle Working Group to discuss design proposals and share real‑world use cases.
• Participate in SIG Node, which owns the core node components and the feature gate that gates the lifecycle conditions.
• Contribute to SIG Apps for workload‑level integrations such as DaemonSet and Job controller enhancements.

All three groups meet regularly on the Kubernetes community mailing lists and in the #sig-node and #sig-apps IRC/Slack channels. Contributions can range from filing issues, submitting KEP drafts, or providing code reviews for the Alpha feature gate implementation. By aligning on a shared signal now, the ecosystem can iteratively evolve controllers to make coordinated, safe decisions during node drains, upgrades, and graceful shutdowns.