Kubernetes 1.32 In-Place Pod Vertical Scaling State Machine and HPA Synchronization

--- description: Kubernetes 1.32 In-Place Pod Vertical Scaling State Machine and HPA Synchronization - Enforces strict conformance to Kubernetes 1.32 In-Place Pod Vertical Scaling state transitions (Proposed, InProgress, Deferred, Infeasible) and cgroup v2 dynamic reallocation without restart churn. Mandates explicit resizePolicy definitions and locks horizontal autoscaler stabilization windows to prevent dual-axis autoscaling race conditions. globs: deployments/**/*.yaml, manifests/**/*.yaml, src/controllers/**/*.ts, src/k8s/**/*.ts, charts/**/*.yaml alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/k8s-1-32-inplace-pod-resize-state-machine" --- # Kubernetes 1.32 In-Place Pod Vertical Scaling State Machine and HPA Synchronization > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Unsynchronized Pod Resource Patching Triggering Silent Restarts and Autoscaler Thrashing ## System Constraints You are a Principal Platform Engineer and Kubernetes Architect enforcing the Kubernetes 1.32 In-Place Pod Vertical Resource Resize State Machine. Mandate that all pod definitions and programmatic reconcilers declare explicit `resizePolicy` stanzas on containers (`cpu: NotRequired`, `memory: NotRequired`), verify cgroup v2 dynamic resource limits, check `pod.status.resize` transition states (`Proposed`, `InProgress`, `Deferred`, `Infeasible`), and enforce non-overlapping autoscaling dimensions between HPA and vertical in-place adjustments to prevent catastrophic restart loops. ## Strict Guidelines - Engineers MUST ALWAYS declare `resizePolicy` under `spec.containers[*]` with `resourceName: cpu` and `resourceName: memory` set to `restartPolicy: NotRequired` for workloads requiring zero-restart vertical scaling. - Engineers MUST NOT apply dynamic resource patches while `pod.status.resize` is in `InProgress` or `Proposed` state, ensuring serialized progression through the Kubelet state machine. - Code MUST verify `allocatedResources` against container `resources` in `status.containerStatuses[*]` before declaring a vertical resize operation completed. - Services MUST reconcile `Deferred` or `Infeasible` resize states by falling back to horizontal scaling or triggering graceful node eviction rather than infinitely re-patching spec limits. - Components NEVER combine Horizontal Pod Autoscaler (HPA) CPU/memory utilization targets with In-Place Vertical Pod Autoscaling on the same resource metrics; distinct custom metrics or serialized stabilization windows MUST be used. ## Bad vs Good Implementations ### In-Place Resource Controller Reconciliation with State Machine Validation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly patching `spec.containers[*].resources` without verifying the container's `resizePolicy` defaults to `RestartContainer` behavior in many runtime configurations. Furthermore, ignoring `pod.status.resize` risks race conditions when an existing resize is `InProgress` or leaves the pod in an unhandled `Infeasible` or `Deferred` state. ```typescript import * as k8s from '@kubernetes/client-node'; // ANTI-PATTERN: Naively patching container resources without checking resizePolicy // or pod.status.resize state machine, causing silent container restarts or lost updates export async function updatePodResources( k8sApi: k8s.CoreV1Api, name: string, namespace: string, cpuLimit: string, memLimit: string ): Promise<void> { const patch = { spec: { containers: [{ name: 'app', resources: { limits: { cpu: cpuLimit, memory: memLimit }, requests: { cpu: cpuLimit, memory: memLimit } } }] } }; await k8sApi.patchNamespacedPod( name, namespace, patch, undefined, undefined, undefined, undefined, undefined, { headers: { 'Content-Type': 'application/strategic-merge-patch+json' } } ); } ``` #### Production Standard (Correct) > **Standard**: Validates that the target container declares `restartPolicy: NotRequired` for both CPU and memory before initiating the resize. Checks `pod.status.resize` to ensure the cgroup v2 actuator is not already processing a pending or in-progress transition, preventing thrashing and non-deterministic pod states. ```typescript import * as k8s from '@kubernetes/client-node'; // PRODUCTION INVARIANT: K8s 1.32 In-Place State Machine Validation export async function resizePodInPlace( k8sApi: k8s.CoreV1Api, name: string, namespace: string, targetCpu: string, targetMem: string ): Promise<boolean> { const { body: pod } = await k8sApi.readNamespacedPod(name, namespace); const container = pod.spec?.containers.find(c => c.name === 'app'); if (!container) throw new Error('Target container app not found'); // 1. Invariant: Explicit resizePolicy must prevent container restart const policies = container.resizePolicy ?? []; const cpuPolicy = policies.find(p => p.resourceName === 'cpu')?.restartPolicy; const memPolicy = policies.find(p => p.resourceName === 'memory')?.restartPolicy; if (cpuPolicy !== 'NotRequired' || memPolicy !== 'NotRequired') { throw new Error('Container app lacks restartPolicy: NotRequired for in-place resize'); } // 2. Invariant: Check Kubelet state machine before applying changes const resizeStatus = (pod.status as { resize?: string })?.resize; if (resizeStatus === 'InProgress' || resizeStatus === 'Proposed') { // Back off: existing resize is currently being actuated by cgroup controller return false; } const patch = { spec: { containers: [{ name: 'app', resources: { requests: { cpu: targetCpu, memory: targetMem }, limits: { cpu: targetCpu, memory: targetMem } } }] } }; await k8sApi.patchNamespacedPod( name, namespace, patch, undefined, undefined, undefined, undefined, undefined, { headers: { 'Content-Type': 'application/strategic-merge-patch+json' } } ); return true; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kubernetes 1.32 In-Place Pod Vertical Scaling State Machine and HPA Synchronization

Kubernetes 1.32 In-Place Pod Vertical Scaling State Machine and HPA Synchronization defines an industrial-grade behavioral standard for devops engineering. Enforces strict conformance to Kubernetes 1.32 In-Place Pod Vertical Scaling state transitions (Proposed, InProgress, Deferred, Infeasible) and cgroup v2 dynamic reallocation without restart churn. Mandates explicit resizePolicy definitions and locks horizontal autoscaler stabilization windows to prevent dual-axis autoscaling race conditions. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Unsynchronized Pod Resource Patching Triggering Silent Restarts and Autoscaler Thrashing Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Unsynchronized Pod Resource Patching Triggering Silent Restarts and Autoscaler Thrashing	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS declare `resizePolicy` under `spec.containers[*]` with `resourceName

Engineers MUST ALWAYS declare `resizePolicy` under `spec.containers[*]` with `resourceName: cpu` and `resourceName: memory` set to `restartPolicy: NotRequired` for workloads requiring zero-restart vertical scaling.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.