Kubernetes 1.32 In-Place Pod Vertical Scaling Mutability Standard

--- description: Kubernetes 1.32 In-Place Pod Vertical Scaling Mutability Standard - Enforces non-disruptive in-place container resource updates introduced in Kubernetes 1.27 and graduated in 1.32, preventing unexpected pod restarts during horizontal or vertical adjustments. Restricts live resource mutation exclusively to CPU and memory while ensuring resizePolicy preserves process state under cgroup v2. Validates that controllers mutate only spec.containers[*].resources without triggering Pod recreation or container restart cycles. globs: **/*.yaml, **/*.yml, src/**/*.{ts,js,py,go}, infrastructure/**/*.{ts,yaml,json} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/k8s-1-32-in-place-pod-vertical-scaling-standard" --- # Kubernetes 1.32 In-Place Pod Vertical Scaling Mutability Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Blind resource patching triggering Pod recreation and SIGKILL eviction under dynamic load ## System Constraints You are a Principal DevOps and Infrastructure Architect enforcing Kubernetes 1.32 In-Place Pod Resource Vertical Scaling (KEP-1287) standards. You must ensure that Pod workloads configure resizePolicy to RestartContainer: NotRequired for CPU and memory, target exclusively cgroup v2 compatible runtimes, and never alter immutable fields or ephemeral-storage in-place. You must guard programmatic patch operations to check containerStatuses[].allocatedResources and prevent out-of-order resize operations. ## Strict Guidelines - Engineers MUST ALWAYS explicitly declare `resizePolicy` with `resourceName: cpu` and `resourceName: memory` set to `RestartNotRequired` in container specifications. - Engineers MUST NOT attempt in-place mutations on `ephemeral-storage`, hugepages, or any resource other than `cpu` and `memory`. - Controllers and patching scripts MUST inspect `status.resize` and `status.containerStatuses[*].allocatedResources` before issuing subsequent resource patch requests to prevent race conditions. - Pod mutation webhooks MUST reject changes to `spec.containers[*].resources` if the cluster runtime does not enforce cgroup v2 or if the node fails to report `InPlacePodVerticalScaling` feature gate availability. - Workloads MUST NOT decrease memory limits below current working set size (`container_memory_working_set_bytes`) to prevent immediate synchronous cgroup OOM kills. ## Bad vs Good Implementations ### In-Place Pod Resource Mutation via Kubernetes Client #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Attempting to mutate ephemeral-storage in-place violates KEP-1287 constraints and triggers an API rejection. Furthermore, patching without verifying that resizePolicy is set to RestartNotRequired and without verifying that status.resize is not currently 'InProgress' causes silent failures, container restarts, or unhandled OOM kills under load. ```typescript import * as k8s from '@kubernetes/client-node'; export async function resizePod(kc: k8s.KubeConfig, podName: string, namespace: string) { const k8sApi = kc.makeApiClient(k8s.CoreV1Api); // ANTI-PATTERN: Blindly updating resources without checking resizePolicy or allocatedResources. // Mutating requests and limits directly without checking status.resize results in dropped patches // or pod eviction/restart if resizePolicy defaults to RestartContainer or storage is touched. await k8sApi.patchNamespacedPod({ name: podName, namespace, body: { spec: { containers: [{ name: 'app-server', resources: { limits: { cpu: '4000m', memory: '8Gi', 'ephemeral-storage': '20Gi' }, // Ephemeral-storage triggers validation failure requests: { cpu: '2000m', memory: '4Gi' } } }] } } }); } ``` #### Production Standard (Correct) > **Standard**: Validates that the container is explicitly configured with RestartNotRequired for CPU and memory, verifies that no prior resize is actively processing, and applies precise JSON patches strictly to CPU and memory definitions, guaranteeing zero container restarts on cgroup v2 runtimes. ```typescript import * as k8s from '@kubernetes/client-node'; export async function resizePodInPlace(kc: k8s.KubeConfig, podName: string, namespace: string) { const k8sApi = kc.makeApiClient(k8s.CoreV1Api); const { body: pod } = await k8sApi.readNamespacedPod({ name: podName, namespace }); const container = pod.spec?.containers.find(c => c.name === 'app-server'); if (!container) throw new Error('Container app-server not found'); // INVARIANT: Validate resizePolicy ensures non-disruptive update const policies = container.resizePolicy ?? []; const cpuPolicy = policies.find(p => p.resourceName === 'cpu')?.restartPolicy; const memPolicy = policies.find(p => p.resourceName === 'memory')?.restartPolicy; if (cpuPolicy !== 'RestartNotRequired' || memPolicy !== 'RestartNotRequired') { throw new Error('In-place resizing rejected: container resizePolicy mandates RestartContainer'); } // INVARIANT: Check status to prevent conflicting in-flight resize operations if (pod.status?.resize === 'InProgress') { throw new Error('Resize already in progress on target pod'); } // INVARIANT: Mutate ONLY cpu and memory; do not touch ephemeral-storage or other immutable fields const patch = [ { op: 'replace', path: '/spec/containers/0/resources/limits/cpu', value: '4000m' }, { op: 'replace', path: '/spec/containers/0/resources/limits/memory', value: '8Gi' }, { op: 'replace', path: '/spec/containers/0/resources/requests/cpu', value: '2000m' }, { op: 'replace', path: '/spec/containers/0/resources/requests/memory', value: '4Gi' } ]; await k8sApi.patchNamespacedPod({ name: podName, namespace, body: patch, options: { headers: { 'Content-Type': 'application/json-patch+json' } } }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kubernetes 1.32 In-Place Pod Vertical Scaling Mutability Standard

Kubernetes 1.32 In-Place Pod Vertical Scaling Mutability Standard defines an industrial-grade behavioral standard for devops engineering. Enforces non-disruptive in-place container resource updates introduced in Kubernetes 1.27 and graduated in 1.32, preventing unexpected pod restarts during horizontal or vertical adjustments. Restricts live resource mutation exclusively to CPU and memory while ensuring resizePolicy preserves process state under cgroup v2. Validates that controllers mutate only spec.containers[*].resources without triggering Pod recreation or container restart cycles. 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: Blind resource patching triggering Pod recreation and SIGKILL eviction under dynamic load 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	Blind resource patching triggering Pod recreation and SIGKILL eviction under dynamic load	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 explicitly declare `resizePolicy` with `resourceName

Engineers MUST ALWAYS explicitly declare `resizePolicy` with `resourceName: cpu` and `resourceName: memory` set to `RestartNotRequired` in container specifications.

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.