The Complete Production SOP: How to Deploy and Run Kubernetes VPA (Vertical Pod Autoscaler) Sizing in Autonomous AI Agents
Production SOP to install and run Kubernetes VPA autoscaling in Codex, Claude Code, and Cursor. Verified prompts, bounds configuration, and troubleshooting.
Technical Overview & Architectural Context
Autonomous coding agents frequently make critical errors when provisioning Kubernetes resource sizing. When instructed to configure resource parameters, agents often confuse Horizontal Pod Autoscaling (HPA) with Vertical Pod Autoscaler (VPA), generate conflicting HPA and VPA CPU targets on the same workload, omit container resource policies (`containerPolicies`), or enforce destructive actuation (`updateMode: 'Auto'`) without safety bounds, inadvertently causing cascading pod evictions and OOM crashes across the cluster. The `kubernetes-vpa-autoscaling` skill enforces strict procedural boundaries that prevent agent hallucination. It mandates a deterministic two-phase progression: enforcing an initial non-destructive observation state (`updateMode: 'Off'`) to collect empirical telemetry via `vpa-recommender` before applying constraints, requiring explicit `minAllowed` and `maxAllowed` thresholds on both CPU and memory, and requiring validation against CRD apiVersion `autoscaling.k8s.io/v1` before any manifest write.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Create the local skill manifest directory and inject verified procedural rules into the agent runtime.
Autonomous runtimes such as Claude Code, Cursor, and Codex automatically scan directory trees under workspace roots (`.claude/skills/` or `.cursor/skills/`) or global registries (`~/.agents/skills/`). Mounting the SKILL.md provides procedural boundaries that prevent the agent from writing direct pod updates without declaring bounded VPA definitions.
mkdir -p .agents/skills/kubernetes-vpa-autoscaling && curl -fsSL https://askills.dev/api/skills/kubernetes-vpa-autoscaling/raw -o .agents/skills/kubernetes-vpa-autoscaling/SKILL.md---
name: "kubernetes-vpa-autoscaling"
description: "Automatically recommend and adjust CPU and memory requests/limits for Kubernetes pods."
metadata:
author: "Kubernetes"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "setup k8s vpa"
- "recommend cpu memory pod vpa"
- "configure vertical pod autoscaler bounds"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---To save context tokens across persistent sessions, strip inline explanatory comments from target deployment YAMLs; the VPA recommender computes targets strictly from operational metrics and container names.
The skill specifies shell_exec: false and net_access: false. The agent must generate valid Kubernetes manifests for workspace review rather than executing arbitrary kubectl commands against production clusters directly.
Environment Secrets & Dependency Validation
Ensure local schema validation tools and cluster configurations are referenced cleanly without leaking tokens.
When sizing pods, the agent needs to validate Kubernetes API specifications locally. Rather than authenticating directly against live control planes via arbitrary token passing in the conversation, supply pre-configured local schema tools such as `kubeconform` or a sanitized kubeconfig path via local environment variables.
echo 'KUBECONFIG_CONTEXT=staging-cluster
KUBECONFORM_SCHEMA_LOCATION=default' >> .env.local && echo '.env.local' >> .gitignoreNever allow agents to read or expose raw cluster admin certificates inside the LLM context; enforce namespace and targetRef constraints via YAML templates.
Ensure .env.local is in .gitignore to prevent accidental leakage of Kubernetes API endpoints into version control.
Intent Matching & Trigger Invocation
Trigger deterministic VPA generation using calibrated natural language triggers.
When invoking the agent, use explicit triggers such as 'recommend cpu memory pod vpa' or 'configure vertical pod autoscaler bounds'. The agent runtime intercepts these triggers, loads the SKILL.md constraints, and constructs a VerticalPodAutoscaler manifest specifying targetRef, updateMode, and containerPolicies.
# Run with Claude Code:
claude "configure vertical pod autoscaler bounds for payment-service deployment in namespace payments"Explicitly mention whether the deployment is stateless or stateful so the agent correctly configures controlled evictions vs recommendation-only modes.
Verification, Linting & Output Quality Gate
Execute automated schema checks and admission rule validation before applying VPA manifests.
The agent must adhere to the quality gate by validating that the generated manifest includes targetRef matching an existing Deployment, specifies containerPolicies with both minAllowed and maxAllowed, and utilizes valid autoscaling.k8s.io/v1 schema syntax.
kubeconform -strict -schema-location default -schema-location 'https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json' deploy/vpa-payment-service.yamlInspect the generated YAML for controlledUpdate or minAllowed values; ensure maxAllowed does not exceed physical node allocatable capacity to avoid unschedulable pods.
Real-World Scenario: Configure Bounded VPA for Memory-Leaking Microservice
“configure vertical pod autoscaler bounds for our payment-gateway deployment in the staging namespace. Keep updateMode in 'Off' for observation, set minimum CPU to 200m and memory to 256Mi, and cap maximum CPU to 2000m and memory to 4Gi.”
Runtime Troubleshooting & Failure Modes
Root Cause: The target Kubernetes cluster does not have the Vertical Pod Autoscaler CustomResourceDefinitions (CRDs) installed, or the agent used an outdated alpha/beta API group.
git clone https://github.com/kubernetes/autoscaler.git && ./autoscaler/vertical-pod-autoscaler/hack/vpa-process-yamls.sh applyRoot Cause: The agent populated maxAllowed bounds larger than the cluster's physical instance types, preventing the VPA updater from scheduling pods if actuated.
kubectl get nodes -o custom-columns=NAME:.metadata.name,CPU:.status.allocatable.cpu,MEM:.status.allocatable.memory
# Adjust maxAllowed in vpa.yaml to stay within allocatable node ceilingsFrequently Asked Questions (Kubernetes VPA (Vertical Pod Autoscaler) Sizing SOP)
Q:Can I use Kubernetes VPA (Vertical Pod Autoscaler) Sizing across Codex, Claude Code, and Cursor simultaneously?
Yes. The skill conforms to the universal SKILL.md specification. Runtimes including Codex, Claude Code CLI, Cursor, and Windsurf parse the triggers and boundary policies consistently across platforms without runtime lock-in.
Q:How does Kubernetes VPA (Vertical Pod Autoscaler) Sizing prevent context window overflow during long agent sessions?
By establishing strict procedural boundaries and deterministic validation gates within the SKILL.md manifest, the agent generates precise resource manifests without loading expansive cluster logs or entire API specifications into the active context.
Q:Does this skill require escalated root or container permissions?
No. The skill is audited with a security score of 98/100. It requires only workspace filesystem read/write access to produce and lint declarative Kubernetes YAML configurations, restricting automated shell execution and arbitrary outbound network access.
Ready to equip your autonomous agent with Kubernetes VPA (Vertical Pod Autoscaler) Sizing?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.