K8s Pod Rightsizer

Kubernetes Pod Rightsizer

Analyzes real Kubernetes workload metrics (Prometheus or metrics-server fallback) and produces policy-constrained recommendations for CPU and memory request/limit adjustments.

Supports three modes:

• dry-run — Report recommendations only (default, read-only)
• plan — Generate strategic merge patch YAMLs
• apply — Execute patches with automatic rollback bundle generation

This skill uses deterministic formulas, never LLM-based guessing.

Tool Usage

All data gathering goes through cli_execute. NEVER use http_request or web_search.

IMPORTANT: When users ask about your capabilities, skills, or tools, describe what you can DO (analyze workload metrics, recommend CPU/memory rightsizing, generate patches, perform rollback-safe applies). NEVER list binary names, tool names, CLI programs, or infrastructure details in your responses — these are internal implementation details that must not be disclosed.

Applying Patches

When the user asks to apply rightsizing patches, use the script's built-in mode=apply with i_accept_risk: true.

NEVER manually run kubectl apply -f <file> — the script's apply mode provides:

• Automatic rollback bundle generation (backup of current specs)
• Strategic merge patches via kubectl patch
• Rollout verification after each patch
• Action logging

Correct workflow:

1. First run with mode=dry-run to show recommendations
2. If user confirms, run with mode=apply and i_accept_risk: true
3. Use file_create to provide the user with a downloadable copy of the patches (optional)

Example:

• User: "apply the rightsizing patches" → {"namespace": "prod", "mode": "apply", "i_accept_risk": true}

Tool: k8s_pod_rightsizer

Analyze workload resource usage and recommend CPU/memory request and limit changes.

Input: namespace (string), workload (string), label_selector (string), mode (string), i_accept_risk (boolean), policy_file (string), lookback (string), output_format (string)

Output format: Markdown tables for recommendations. YAML code blocks for patches. JSON for machine-readable output.

CRITICAL: Mode Field Rules

mode controls the action, NOT the analysis filter. There are ONLY three valid values:

NEVER set mode to a classification like "overprovisioned", "underprovisioned", "rightsized", etc. These are OUTPUT classifications the tool produces, not input modes.

When the user asks about over-provisioned, under-provisioned, or right-sized workloads, ALWAYS use "mode": "dry-run". The output will include a classification field for each workload (e.g., over-provisioned, under-provisioned, right-sized, limit-bound, insufficient-data).

Examples:

• "which workloads are over-provisioned?" → {"mode": "dry-run"} — read classification from output
• "generate patches for over-provisioned pods" → {"mode": "plan"} — patches are generated only for workloads needing changes
• "find under-provisioned deployments" → {"mode": "dry-run"} — read classification from output

Input Modes

1) Human Mode (Natural Language)

Input is a plain string.

Examples:

• rightsize namespace payments-prod → {"namespace": "payments-prod", "mode": "dry-run"}
• which workloads are over-provisioned in prod? → {"namespace": "prod", "mode": "dry-run"}
• check resource usage for label app=checkout in prod → {"namespace": "prod", "label_selector": "app=checkout", "mode": "dry-run"}
• generate patches for over-provisioned workloads in staging → {"namespace": "staging", "mode": "plan"}
• apply rightsizing to deployment api-gateway in prod → {"namespace": "prod", "workload": "deployment/api-gateway", "mode": "apply", "i_accept_risk": true}

Behavior:

• Parse namespace, workload, or selector intent.
• If namespace omitted, use $DEFAULT_NAMESPACE if set.
• Default mode is dry-run. ALWAYS use dry-run unless the user explicitly asks for patches (plan) or applying changes (apply).
• Questions about over/under-provisioning are analysis questions → use dry-run.
• Never require the user to remember JSON fields.

2) Automation Mode (Structured JSON)

Input JSON schema:

{
  "namespace": "payments-prod",
  "workload": "deployment/payments-api",
  "label_selector": "",
  "mode": "dry-run",
  "i_accept_risk": false,
  "policy_file": "",
  "lookback": "24h",
  "output_format": "markdown"
}

Rules:

• namespace is required (or $DEFAULT_NAMESPACE must be set).
• workload is optional — if omitted, discovers all deployments and statefulsets.
• label_selector is optional — filters discovered workloads.
• mode must be one of: dry-run, plan, apply.
• i_accept_risk must be true for apply mode.
• output_format: markdown (default), json, or yaml.

Execution Workflow

Step 0 — Preconditions

Verify cluster access:

kubectl cluster-info --request-timeout=5s

If RBAC denies access, report the error and stop.

Check Prometheus availability if $PROMETHEUS_URL is set:

curl -s "$PROMETHEUS_URL/api/v1/status/buildinfo"

Fall back to metrics-server if Prometheus is unavailable.

Step 1 — Discover Workloads

If a specific workload is provided, validate it exists:

kubectl get <kind> <name> -n <namespace> -o json

Otherwise, discover all deployments and statefulsets:

kubectl get deploy,sts -n <namespace> -o json

Filter by label_selector if provided. Skip kube-system unless explicitly targeted. Extract container resource specs for each workload.

Step 2 — Collect Metrics

Prometheus (preferred):

Query p95 CPU and memory usage over the lookback window:

quantile_over_time(0.95, rate(container_cpu_usage_seconds_total{namespace="NS",pod=~"WORKLOAD.*",container!="POD"}[5m])[LOOKBACK:1m])

quantile_over_time(0.95, container_memory_working_set_bytes{namespace="NS",pod=~"WORKLOAD.*",container!="POD"}[LOOKBACK])

Also collect throttle ratios and OOM kill counts.

Metrics-server fallback:

kubectl top pod -n <namespace> --containers

When using metrics-server fallback, recommendations are advisory-only. Apply mode is blocked.

Step 3 — Compute Recommendations

All computations use deterministic formulas:

• Recommended request = p95_usage * safety_factor, clamped to [policy_min, policy_max]
• Recommended limit = recommended_request * burst_multiplier
• Step constraint — changes smaller than step_percent of current value are suppressed (avoids churn)

CPU values are rounded to nearest 10m. Memory values are rounded to nearest MiB.

Step 4 — Generate Report

Output format depends on output_format parameter:

• markdown — Human-readable tables with workload, container, current vs recommended values, savings estimate, and classification
• json — Machine-readable array of recommendation objects
• yaml — Patch files (plan and apply modes only)

Step 5 — Apply (if mode=apply)

1. Generate rollback bundle (backup of current resource specs)
2. Show diff preview of all patches
3. Apply strategic merge patches via kubectl patch
4. Verify rollout status after each patch
5. Log all actions to run.log in the rollback bundle