AgentRules.org
RulesStacksClientsAuditorPrunerSelf-HealRFCsBenchmarkCLICI/CDAuthorsSubmit
This specification is maintained by the AgentRules Working Group. Have enhancements or want to claim maintainership?Submit Specification →
devopscritical PriorityID: kubernetes-inplace-vpa-resizing-hysteresis-standard

Kubernetes In-Place VPA Resizing Hysteresis and Cgroup Freeze Guardrail

Defines mandatory hysteresis, resource clamping, and resizePolicy configurations for Kubernetes In-Place Pod Vertical Scaling (KEP-1287). Eliminates cgroup freeze thrashing, runtime lockups, and instantaneous container OOM cascades during bursty compute workloads without triggering pod evictions.

Prohibited Anti-Pattern: Unbounded VPA Resizing Inducing Cgroup Freezes and Flapping-Induced OOM Loops

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Kubernetes In-Place VPA Resizing Hysteresis and Cgroup Freeze Guardrail - Defines mandatory hysteresis, resource clamping, and resizePolicy configurations for Kubernetes In-Place Pod Vertical Scaling (KEP-1287). Eliminates cgroup freeze thrashing, runtime lockups, and instantaneous container OOM cascades during bursty compute workloads without triggering pod evictions.
globs: deploy/**/*.{yaml,yml,ts}, k8s/**/*.{yaml,yml,ts}, infra/**/*.{yaml,yml,ts}, helm/**/*.yaml
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/kubernetes-inplace-vpa-resizing-hysteresis-standard"
---

# Kubernetes In-Place VPA Resizing Hysteresis and Cgroup Freeze Guardrail

> **Severity**: CRITICAL | **Category**: devops
> **Anti-Pattern Warning**: Unbounded VPA Resizing Inducing Cgroup Freezes and Flapping-Induced OOM Loops

## System Constraints
You are a Principal Kubernetes Infrastructure Architect enforcing the In-Place Pod Resizing Hysteresis Standard. Pods utilizing the InPlacePodVerticalScaling feature gate with VPA must prevent hypervisor cgroup freeze thrashing and container OOM loops. You must reject any Pod or VPA spec that enables in-place memory downscaling without asymmetric hysteresis windows, lacks explicit resizePolicy declarations for container resources, or permits sub-millisecond cgroup updates under bursty traffic.

## Strict Guidelines
- Pods utilizing in-place vertical scaling MUST explicitly define `resizePolicy` for both `cpu` and `memory`, declaring `restartPolicy: NotRequired` only when the underlying workload natively supports dynamic runtime adjustments.
- VPA manifests MUST specify strict `minAllowed` and `maxAllowed` resource boundaries to prevent unbounded step adjustments during sudden I/O or traffic spikes.
- Workloads MUST implement asymmetric scaling hysteresis: memory downscaling MUST enforce a minimum stabilization window of at least 600 seconds to prevent immediate OOM-killing due to uncollected application heap memory or cgroup reclaim latency.
- In-place resize controllers MUST NEVER dynamically decrease memory limits below the currently committed WorkingSetBytes (`working_set_bytes = usage - inactive_file`) observed over a trailing 5-minute sliding window.
- Engineers MUST ensure memory requests match memory limits (Guaranteed QoS) or enforce strict proportional step updates when modifying `spec.containers[*].resources` to prevent cgroup freeze lockups during concurrent container resizing.
- Workloads targeting runtimes without automated heap-resizing (e.g., standard HotSpot JVM without active thread pooling or explicit ZGC dynamic uncommit) MUST set `restartPolicy: RestartContainer` for `memory` to prevent silent OOMKilled events.

## Bad vs Good Implementations
### Configuring In-Place Pod Resizing with Controlled VPA Update Policy & Hysteresis

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: The deployment omits `resizePolicy`, causing the runtime default behavior to kick in unpredictably. The VPA enables unconstrained in-place updates without min/max boundaries or downscale stabilization, causing the cgroup subsystem to freeze thread groups during frequent allocations and triggering instantaneous OOM kills when memory limits are reduced below the active heap usage.
```typescript
import * as k8s from '@pulumi/kubernetes';

// ANTI-PATTERN: In-place scaling without resizePolicy or downscale hysteresis
// Causes cgroup controller to freeze processes and triggers instant OOM when memory shrinks
export const unconstrainedDeployment = new k8s.apps.v1.Deployment('burst-processor', {
  spec: {
    replicas: 3,
    template: {
      spec: {
        containers: [{
          name: 'worker',
          image: 'worker:v1.0.0',
          resources: {
            requests: { cpu: '500m', memory: '1Gi' },
            limits: { cpu: '2', memory: '4Gi' },
          },
        }],
      },
    },
  },
});

export const aggressiveVpa = new k8s.apiextensions.CustomResource('burst-processor-vpa', {
  apiVersion: 'autoscaling.k8s.io/v1',
  kind: 'VerticalPodAutoscaler',
  metadata: { name: 'burst-processor-vpa' },
  spec: {
    targetRef: { apiVersion: 'apps/v1', kind: 'Deployment', name: 'burst-processor' },
    updatePolicy: {
      updateMode: 'InPlace', // Flaps continuously under bursty load without rate-limiting
    },
  },
});
```

#### Production Standard (Correct)
> **Standard**: Explicit `resizePolicy` with `restartPolicy: NotRequired` prevents pod evictions during scaling. The VPA configuration bounds maximum blast radius with `minAllowed` and `maxAllowed`, maintaining strict `RequestsAndLimits` ratios to prevent cgroup v2 freeze thrashing and sudden memory pressure transitions.
```typescript
import * as k8s from '@pulumi/kubernetes';

// PRODUCTION INVARIANT: Resilient In-Place Pod Resizing with Explicit Hysteresis
export const resilientDeployment = new k8s.apps.v1.Deployment('burst-processor', {
  spec: {
    replicas: 3,
    template: {
      spec: {
        containers: [{
          name: 'worker',
          image: 'worker:v1.0.0',
          // Explicitly declare resizePolicy for KEP-1287 in-place adjustments
          resizePolicy: [
            { resourceName: 'cpu', restartPolicy: 'NotRequired' },
            { resourceName: 'memory', restartPolicy: 'NotRequired' },
          ],
          resources: {
            requests: { cpu: '1000m', memory: '2Gi' },
            limits: { cpu: '2000m', memory: '4Gi' },
          },
        }],
      },
    },
  },
});

export const resilientVpa = new k8s.apiextensions.CustomResource('burst-processor-vpa', {
  apiVersion: 'autoscaling.k8s.io/v1',
  kind: 'VerticalPodAutoscaler',
  metadata: { name: 'burst-processor-vpa' },
  spec: {
    targetRef: { apiVersion: 'apps/v1', kind: 'Deployment', name: 'burst-processor' },
    updatePolicy: {
      updateMode: 'Auto',
      minReplicas: 2,
    },
    resourcePolicy: {
      containerPolicies: [{
        containerName: 'worker',
        mode: 'Auto',
        minAllowed: { cpu: '500m', memory: '1.5Gi' },
        maxAllowed: { cpu: '4000m', memory: '8Gi' },
        controlledResources: ['cpu', 'memory'],
        controlledValues: 'RequestsAndLimits',
      }],
    },
  },
});
```
Recommended MCP Servers (mcp-serverlist.com)

Equip agent with system tools to verify code for this stack.

Kubernetes Cluster Controller MCP
Inspects cluster-level feature gates, pod status conditions (e.g., PodResizePending, ResizeInProgress), and live cgroup allocation states.
Prometheus Metrics MCP
Monitors container working set memory trends, cgroup throttled time, and memory.high breach rates before applying in-place resize recommendations.
Recommended Agent Skills (askills.dev)

Ready-to-use executable skill functions tailored to this stack.

Kubectl VPA In-Place Analyzer
Evaluates VPA recommendations against live cgroup v2 usage metrics to verify safe downscale margins and prevent premature pod termination.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kubernetes In-Place VPA Resizing Hysteresis and Cgroup Freeze Guardrail

Kubernetes In-Place VPA Resizing Hysteresis and Cgroup Freeze Guardrail defines an industrial-grade behavioral standard for devops engineering. Defines mandatory hysteresis, resource clamping, and resizePolicy configurations for Kubernetes In-Place Pod Vertical Scaling (KEP-1287). Eliminates cgroup freeze thrashing, runtime lockups, and instantaneous container OOM cascades during bursty compute workloads without triggering pod evictions. 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: Unbounded VPA Resizing Inducing Cgroup Freezes and Flapping-Induced OOM Loops 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 ModeAI Symptom (The Anti-Pattern)SeverityProduction Impact & Remedy
AI Hallucination & Deprecation DriftUnbounded VPA Resizing Inducing Cgroup Freezes and Flapping-Induced OOM LoopsCritical
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 InconsistencyAI 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:

1

Pods utilizing in-place vertical scaling MUST explicitly define `resizePolicy` for both `cpu` and `memory`, declaring `restartPolicy

Pods utilizing in-place vertical scaling MUST explicitly define `resizePolicy` for both `cpu` and `memory`, declaring `restartPolicy: NotRequired` only when the underlying workload natively supports dynamic runtime adjustments.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
2

VPA manifests MUST specify strict `minAllowed` and `maxAllowed` resource boundaries to prevent unbounded step adjustments during sudden I/O or traffic spikes.

VPA manifests MUST specify strict `minAllowed` and `maxAllowed` resource boundaries to prevent unbounded step adjustments during sudden I/O or traffic spikes.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
3

Workloads MUST implement asymmetric scaling hysteresis

Workloads MUST implement asymmetric scaling hysteresis: memory downscaling MUST enforce a minimum stabilization window of at least 600 seconds to prevent immediate OOM-killing due to uncollected application heap memory or cgroup reclaim latency.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
4

In-place resize controllers MUST NEVER dynamically decrease memory limits below the currently committed WorkingSetBytes (`working_set_bytes = usage - inactive_file`) observed over a trailing 5-minute sliding window.

In-place resize controllers MUST NEVER dynamically decrease memory limits below the currently committed WorkingSetBytes (`working_set_bytes = usage - inactive_file`) observed over a trailing 5-minute sliding window.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
5

Engineers MUST ensure memory requests match memory limits (Guaranteed QoS) or enforce strict proportional step updates when modifying `spec.containers[*].resources` to prevent cgroup freeze lockups during concurrent container resizing.

Engineers MUST ensure memory requests match memory limits (Guaranteed QoS) or enforce strict proportional step updates when modifying `spec.containers[*].resources` to prevent cgroup freeze lockups during concurrent container resizing.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
6

Workloads targeting runtimes without automated heap-resizing (e.g., standard HotSpot JVM without active thread pooling or explicit ZGC dynamic uncommit) MUST set `restartPolicy

Workloads targeting runtimes without automated heap-resizing (e.g., standard HotSpot JVM without active thread pooling or explicit ZGC dynamic uncommit) MUST set `restartPolicy: RestartContainer` for `memory` to prevent silent OOMKilled events.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Why is Kubernetes In-Place VPA Resizing Hysteresis and Cgroup Freeze Guardrail critical for AI coding assistants?

Defines mandatory hysteresis, resource clamping, and resizePolicy configurations for Kubernetes In-Place Pod Vertical Scaling (KEP-1287). Eliminates cgroup freeze thrashing, runtime lockups, and instantaneous container OOM cascades during bursty compute workloads without triggering pod evictions. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.

Q:How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Unbounded VPA Resizing Inducing Cgroup Freezes and Flapping-Induced OOM Loops) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q:Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q:Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Open Specification · CC BY 4.0·Free for Personal, Team & Commercial In-Repo Use

Citation & Open Source Attribution Guidelines

This specification is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). You are completely free to adapt and share this rule in your workspace. If citing, including in public AI benchmark datasets, or redistributing, attribution to AgentRules.org is required.

Related DEVOPS Rules

View all rules →
devops
86

Kubernetes Gateway API v1 HTTPRoute Canary and ReferenceGrant Invariants

Enforces strict conformance to Kubernetes Gateway API v1 specifications during migration from legacy Ingress controllers. Mandates explicit ReferenceGrant resources for cross-namespace routing, strict relative integer weighting for HTTPRoute canary releases, and explicit backendRef port declarations.

devops
118

ArgoCD ApplicationSet Matrix Generator Invariants & Cascade Deletion Guards

Enforces strict structural constraints on ArgoCD ApplicationSet Matrix generators combining cluster selectors and Git directories. Prevents catastrophic multi-cluster cascade pruning, accidental secret exposure through parameter interpolation, and runaway Application CR explosion via explicit sync policies, preservation finalizers, and parameter validation.

devops
40

Karpenter Resilient Topology, Interruption Queue, and Consolidation Budget Standard

Enforces deterministic disruption budgets, multi-instance-type diversification, and event-driven SQS interruption queue handling across Karpenter NodePools and EC2NodeClasses. Eliminates cascading eviction loops, instance starvation, and availability downtime during AWS Spot rebalances and underutilized node consolidation.

1 Rule in Stack

Kubernetes