OptiPod

OptiPod is an open-source Kubernetes operator that makes explainable recommendations for CPU and memory requests/limits, and can apply them when you explicitly opt in.

If you're new to operators or autoscaling: OptiPod is designed to be calm and safe to try.

• Recommend mode is the safe way to start.
• Nothing mutates without opt-in (you must explicitly choose mode: Auto).

Why OptiPod exists

Kubernetes resources are often set once and never revisited. Teams want to tighten requests/limits, but hesitate because:

• GitOps controllers can fight with automated mutations.
• Memory tuning can cause OOMKills and noisy rollouts.
• It’s hard to trust a tool if you can’t explain its recommendations.

OptiPod exists to provide a GitOps-safe, policy-driven way to recommend first, then apply when you’re ready.

What OptiPod will NOT do

• Will not mutate workloads unless explicitly configured
• Will not override GitOps ownership
• Will not require a SaaS backend

Note: OptiPod does not currently guard memory decreases — a recommended decrease is applied in full. See the Safety model for details.

Quick Start (safe Recommend mode)

In Recommend mode:

• No resources are changed.
• No pods are restarted.
• Recommendations are written as annotations on individual workloads for review.
• Policy status shows aggregate counts (workloads discovered/processed) but not individual recommendations.

1) Install

Recommended: Helm Installation

# Install from the OCI registry (recommended)
# Omit --version to install the latest chart.
VERSION=<latest> # see https://github.com/Sagart-cactus/optipod/releases/latest
helm install optipod oci://ghcr.io/sagart-cactus/charts/optipod \
  --version "${VERSION}" \
  --namespace optipod-system \
  --create-namespace

Alternative: kubectl

# For ArgoCD/GitOps environments (webhook strategy)
kubectl apply -f https://github.com/Sagart-cactus/optipod/releases/latest/download/install-webhook.yaml

# For traditional Kubernetes environments (SSA strategy)
kubectl apply -f https://github.com/Sagart-cactus/optipod/releases/latest/download/install.yaml

Automated installation script:

curl -sSL https://raw.githubusercontent.com/Sagart-cactus/optipod/main/config/webhook/install.sh | bash

2) Create a minimal policy (Recommend mode)

Save as optipod-policy.yaml:

apiVersion: optipod.optipod.io/v1alpha1
kind: OptimizationPolicy
metadata:
  name: safe-recommendations
  namespace: default
spec:
  mode: Recommend

  selector:
    workloadSelector:
      matchLabels:
        optipod.io/enabled: "true"

  metricsConfig:
    provider: metrics-server
    rollingWindow: 24h
    percentile: P90
    safetyFactor: 1.2

  resourceBounds:
    cpu:
      min: "100m"
      max: "4000m"
    memory:
      min: "128Mi"
      max: "8Gi"

  updateStrategy:
    allowInPlaceResize: true
    allowRecreate: false
    updateRequestsOnly: true

Apply it:

kubectl apply -f optipod-policy.yaml

3) Label a workload and review recommendations

kubectl label deployment my-app optipod.io/enabled=true
kubectl describe optimizationpolicy safe-recommendations -n default
# View individual workload recommendations:
kubectl get deployment my-app -o yaml | grep -A5 -B5 "optipod.io/recommendation"

Safety confirmation: as long as spec.mode: Recommend, OptiPod will not change workload specs.

Where recommendations are stored

OptiPod stores recommendations in two places:

Individual Workload Annotations

Each workload (Deployment, StatefulSet, DaemonSet) gets recommendation annotations:

metadata:
  annotations:
    optipod.io/managed: "true"
    optipod.io/policy: "safe-recommendations"
    optipod.io/last-recommendation: "2025-01-04T10:30:00Z"
    optipod.io/recommendation.app-container.cpu-request: "250m"
    optipod.io/recommendation.app-container.memory-request: "512Mi"
    optipod.io/recommendation.app-container.cpu-limit: "500m"     # Present when updateRequestsOnly=false
    optipod.io/recommendation.app-container.memory-limit: "1Gi"   # Present when updateRequestsOnly=false

Policy Status (Aggregate Only)

The OptimizationPolicy status shows aggregate counts, not individual recommendations:

status:
  workloadsDiscovered: 150
  workloadsProcessed: 145
  workloadsByType:
    deployment: 120
    statefulset: 25
    daemonset: 5
  lastReconciliation: "2025-01-04T10:30:00Z"

This design keeps the policy status lightweight while making individual recommendations visible on each workload for GitOps workflows.

What OptiPod actually does (high-level flow)

1. Discovers workloads selected by your policy (namespaces, labels, workload types)
2. Reads CPU/memory usage from your metrics backend
3. Computes recommendations (percentiles over a rolling window + safety factor)
4. Applies policy-driven safety (resource bounds and safety factor; the memory-decrease and change-rate guards are not implemented yet)
5. Either:
   • writes explainable recommendations as annotations on individual workloads (Recommend mode), or
   • applies changes via Server-Side Apply (SSA) (Auto mode)

Key concepts / terminology

Term	Meaning (one line)
Operator	A controller that continuously reconciles desired state in Kubernetes.
GitOps	A workflow where cluster state is driven from Git (e.g. ArgoCD/Flux).
Server-Side Apply (SSA)	Kubernetes apply mode that tracks field ownership to avoid conflicts.
VPA	Vertical Pod Autoscaler; recommends (and can apply) resource changes.

Operational modes

• Recommend: Compute and record recommendations; do not mutate workloads.
• Auto: Apply recommendations (within your safety policy) using the configured strategy.
• Disabled: Stop processing workloads under the policy.

Update Strategies

OptiPod supports two strategies for applying resource recommendations:

Webhook Strategy (Default)

Best for: ArgoCD, GitOps workflows, environments without SSA permissions

• ✅ ArgoCD Compatible: Works seamlessly with GitOps tools
• ✅ No SSA Required: Doesn't need Server Side Apply permissions
• ✅ Automatic Application: Applies changes during pod creation
• ❌ Infrastructure Required: Needs webhook server and certificates

spec:
  updateStrategy:
    strategy: webhook                    # Use webhook strategy
    rolloutStrategy: onNextRestart      # Control when changes take effect

SSA Strategy (Traditional)

Best for: Direct Kubernetes API access, environments with full SSA permissions

• ✅ Direct Updates: Immediate API updates with Server Side Apply
• ✅ No Infrastructure: No additional components required
• ❌ ArgoCD Conflicts: May conflict with GitOps tools
• ❌ SSA Required: Needs Server Side Apply permissions

spec:
  updateStrategy:
    strategy: ssa                       # Use SSA strategy
    useServerSideApply: true           # Enable SSA features

Safety model

OptiPod is built around conservative defaults and explicit, policy-driven controls:

• Policy-driven safety: min/max bounds and safety factors (the memory-decrease and change-rate guards are not implemented yet).
• Memory handling: recommendations are derived from observed usage and clamped to your explicit bounds; memory decreases are currently applied in full.
• GitOps-safe: supports both webhook strategy (ArgoCD compatible) and Server-Side Apply (SSA) for different environments.
• Explainable recommendations: usage window, percentile choice, and safety margin are visible before applying.
• Update strategy control: allow/disallow in-place resize; block disruptive recreation unless you opt in.

OptiPod vs VPA comparison

Legend: ✅ supported, ❌ not supported, ⚠️ supported with caveats.

Capability	OptiPod	Kubernetes VPA
GitOps-safe (ArgoCD compatible)	✅	❌
Server-Side Apply (SSA) support	✅	❌
Safe by default (Recommend mode)	✅	⚠️
Explainable recommendations	✅	⚠️
Policy-driven safety	✅	⚠️
Multiple update strategies	✅	❌

⚠️ Typically means you can achieve the outcome, but it’s easier to run into GitOps conflicts and/or less predictable rollouts depending on configuration and workload constraints.

Who OptiPod is for

• Platform teams running GitOps-managed clusters
• SREs who want safer, Recommend mode first workflows
• FinOps partners who need guardrails and visibility (without a SaaS dependency)
• Teams who want to start with recommendations and adopt automation gradually

Metrics & observability

• Metrics backends: metrics-server and prometheus
• Exposes Prometheus metrics from the controller
• Emits Kubernetes events for important actions and failures
• Writes recommendations as annotations on workloads and aggregate results to OptimizationPolicy status

Estimate impact before switching to Auto

Before you change a policy to mode: Auto, you can generate a report that summarizes the replica-weighted impact (total CPU/memory request deltas across pods) based on OptiPod’s recommendations.

This is especially useful to answer: “If I opt in to Auto, what will change, and by how much?”

Generate an HTML report:

curl -fsSL https://raw.githubusercontent.com/Sagart-cactus/optipod/main/scripts/optipod-recommendation-report.sh -o optipod-recommendation-report.sh
chmod +x optipod-recommendation-report.sh
./optipod-recommendation-report.sh -o html -f optipod-impact.html

Generate a JSON report for programmatic analysis:

./optipod-recommendation-report.sh -o json -f optipod-impact.json

The report only includes workloads that have OptiPod recommendation annotations (generated in Recommend mode), and highlights warnings (for example: when updateRequestsOnly=true but recommended requests would exceed existing limits).

How the impact report works:

• Scans all workloads in the cluster for OptiPod recommendation annotations
• Consolidates individual workload recommendations into aggregate totals
• Calculates replica-weighted impact (recommendation delta × number of pods)
• Provides both per-workload details and cluster-wide summaries
• Available in JSON format for automation or HTML for human review

Project status

OptiPod has core functionality implemented and tested, and is in active development.

• Production-ready features

  • GitOps-safe Server-Side Apply (SSA): OptiPod claims ownership only of CPU/memory request/limit fields.
  • Multiple operational modes: Recommend / Auto / Disabled.
  • Policy-driven safety: bounds, safety factors, and controlled application strategies.
  • Explainable recommendations: visible inputs and margins before applying.
  • Observability: Prometheus metrics, Kubernetes events, and detailed policy status.

• Work in progress

  • Per-policy metrics provider selection (currently configured globally)
  • Custom metrics provider plugin framework

• Documentation

  • Installation Guide
  • Example Policies
  • Impact Report
  • CRD Reference
  • Prometheus Setup
  • ArgoCD Integration
  • Pre-commit Setup
  • Webhook Troubleshooting
  • Webhook Examples

• Docs: docs/ (source) and website/docs/ (rendered site)

• Roadmap: ROADMAP.md

Contributing & governance

• Contributing guide: CONTRIBUTING.md
• Governance: GOVERNANCE.md
• Code of Conduct: CODE_OF_CONDUCT.md

Quick Start for contributors

git clone https://github.com/Sagart-cactus/optipod.git
cd optipod
make setup-pre-commit
make test-fast   # non-mutating fast gate: unit + envtest + clusterless

Testing

All test entry points are discoverable via make help. None of them mutate tracked files, switch your kubectl context, or touch existing clusters.

Command	What it runs
make test-fast	Fast gate: short unit, envtest (real local API server) and clusterless tests. Never regenerates or formats tracked files.
make vet / make lint	go vet and pinned golangci-lint.
make test-e2e-smoke	One-command installed-controller smoke suite on an ephemeral, uniquely named Kind cluster: preflight, build/load/install the checkout controller once, smoke specs, teardown.
make test-e2e-conformance	Full conformance suite (includes all smoke coverage) over the same hermetic harness.
make test-e2e-labels E2E_LABELS="smoke && webhook"	Focused run of the Kind suite by Ginkgo label (smoke, conformance, webhook, rbac, observability, failure-recovery, ...).

Kind suite prerequisites: Docker, Kind v0.31.0, kubectl, and kustomize v5.8.1 on PATH (all other inputs are pinned by the harness; preflight fails early with a remedy if one is missing). Every run writes JUnit (junit.xml), phase timings (timings.json) and, on failure, a redacted diagnostics bundle to the git-ignored test/e2e/artifacts/run-<id>/. Normal runs delete only their own cluster; KEEP_CLUSTER=1 make test-e2e-smoke retains it and prints private-kubeconfig inspection, focused-reuse (make test-e2e-reuse) and disposal commands. See docs/testing/README.md for the full architecture, coverage matrix and debugging guide, and docs/testing/final-report.md for the measured final mission report (commands, timings, reliability ledger, follow-ups).

CI mirrors these tiers: pull requests and pushes that touch controller, API, chart, manifest, test, Make or workflow inputs run the smoke job (.github/workflows/e2e.yml); the full conformance suite runs nightly and on manual dispatch; the fast gate runs on every push and pull request (.github/workflows/test.yml).

Building from source (development)

make build
make run

Roadmap

See ROADMAP.md for planned work and explicit non-goals.

License

Apache 2.0. See LICENSE.

Final safety note

Start in Recommend mode, set conservative bounds, and validate recommendations in a non-production environment before enabling mode: Auto.