Key Terminology

Understanding these key terms will help you work effectively with OptiPod.

A Kubernetes operator is a software extension that uses custom resources to manage applications and their components. OptiPod is an operator that manages resource optimization for your workloads.

Key characteristics:

• Runs as a deployment in your cluster
• Watches for OptimizationPolicy resources
• Analyzes workload metrics
• Generates and applies recommendations

A Custom Resource Definition (CRD) that defines how OptiPod should optimize workloads. Each policy specifies:

• Target workloads: Which resources to optimize (by namespace, labels, workload types)
• Operational mode: Recommend, Auto, or Disabled
• Metrics configuration: Provider, rolling window, percentile, safety factor
• Resource bounds: Min/max limits for CPU and memory
• Update strategy: How to apply recommendations (SSA or webhook)

Example:

apiVersion: optipod.optipod.io/v1alpha1
kind: OptimizationPolicy
metadata:
  name: production-policy
spec:
  mode: Recommend
  selector:
    workloadSelector:
      matchLabels:
        env: production
    workloadTypes:
      include: [Deployment, StatefulSet]
  metricsConfig:
    provider: prometheus
    rollingWindow: 7d
  resourceBounds:
    cpu:
      min: 10m
      max: 2000m
    memory:
      min: 64Mi
      max: 4Gi
  updateStrategy:
    strategy: webhook

A Kubernetes resource that runs containers. OptiPod supports:

• Deployments: Stateless applications
• StatefulSets: Stateful applications
• DaemonSets: Node-level services

Note: Jobs and CronJobs are not currently supported.

A suggested change to a workload’s resource requests and limits, based on actual usage patterns. Recommendations are calculated using:

• Percentile-based analysis: P50, P90, or P99 of historical usage
• Safety factor: Multiplier applied to percentile (default 1.2)
• Resource bounds: Min/max constraints from policy
• Weight: Policy priority when multiple policies match

Recommendations are stored as per-resource annotations on the workload:

• optipod.io/recommendation.<container-name>.cpu-request
• optipod.io/recommendation.<container-name>.memory-request
• optipod.io/recommendation.<container-name>.cpu-limit
• optipod.io/recommendation.<container-name>.memory-limit

A deployment methodology where Git is the single source of truth for infrastructure and application configuration. Changes are made through Git commits and automatically applied to the cluster.

OptiPod’s GitOps compatibility:

With Webhook Strategy:

• Recommend mode stores suggestions as annotations only
• Workload specs in Git remain unchanged
• You review and commit changes to Git if desired
• Webhook applies recommendations at pod creation time
• No conflicts with ArgoCD/Flux

With SSA Strategy:

• OptiPod directly updates resource fields in workload specs
• May require configuring GitOps tools to ignore resource fields
• Use ArgoCD’s ignoreDifferences or SSA sync options

A Kubernetes feature that allows multiple controllers to manage different fields of the same resource without conflicts. OptiPod can use SSA to apply recommendations directly to workload specs.

Benefits:

• No webhook required
• Direct field updates
• Clear field ownership
• In-place pod resize support (Kubernetes 1.27+)

The source of resource usage data. OptiPod supports:

• Prometheus: Full-featured metrics with historical data (recommended)
• metrics-server: Basic CPU/memory metrics with sampling
• Custom providers: Integrate your own metrics source (future)

The time period OptiPod analyzes to generate recommendations. Longer windows provide more stable recommendations but take longer to react to changes.

Typical values:

• 7 days: Balanced (default)
• 14 days: More stable, slower to adapt
• 24 hours: Faster adaptation, less stable

Configuration:

metricsConfig:
  rollingWindow: 7d  # or 24h, 14d, 30d

The statistical measure used to determine resource recommendations. OptiPod supports P50, P90, and P99.

Example:

• P90 CPU = 250m means 90% of the time, CPU usage is below 250m
• P99 provides more headroom for spikes
• P50 is more aggressive but riskier

Configuration:

metricsConfig:
  percentile: P90  # or P50, P99

A multiplier applied to the selected percentile to add headroom. Default is 1.2 (20% above percentile).

Example:

• P90 = 250m, safety factor = 1.2
• Recommendation = 250m × 1.2 = 300m

Configuration:

metricsConfig:
  safetyFactor: 1.2  # 1.0 = no headroom, 1.5 = 50% headroom

The amount of CPU/memory Kubernetes guarantees for a container. Used for scheduling decisions.

Impact:

• Too low: Pod may be scheduled on overloaded nodes, leading to throttling or OOM
• Too high: Wastes cluster capacity and increases costs

The maximum amount of CPU/memory a container can use.

Impact:

• CPU: Container is throttled if exceeded
• Memory: Container is OOM-killed if exceeded

OptiPod can calculate limits based on requests using multipliers:

updateStrategy:
  limitConfig:
    cpuLimitMultiplier: 1.0      # limit = request × 1.0
    memoryLimitMultiplier: 1.1   # limit = request × 1.1

Or you can update only requests and leave limits unchanged:

updateStrategy:
  updateRequestsOnly: true

Kubernetes’ built-in solution for adjusting resource requests/limits. OptiPod is an alternative designed to be more GitOps-friendly and explainable.

Key differences:

• VPA uses webhooks that can conflict with GitOps
• OptiPod offers webhook strategy that’s GitOps-safe
• OptiPod provides explainable recommendations with percentile-based calculations

OptiPod currently has no memory decrease guard: a recommended memory decrease is applied in full, exactly like any other recommendation, constrained only by resource bounds and the safety factor.

The allowUnsafeMemoryDecrease field is accepted and validated by the CRD but is not implemented, so setting it has no effect:

updateStrategy:
  allowUnsafeMemoryDecrease: false  # Accepted, but not enforced today

⚠️ Status: This feature is not yet implemented. The configuration is accepted but has no effect.

For safer memory optimization, OptiPod plans to support applying large decreases incrementally:

updateStrategy:
  gradualDecreaseConfig:
    enabled: true
    memoryDecreasePercentage: 10      # Max 10% per reconciliation
    minimumDecreaseThreshold: 100Mi   # Apply gradually if decrease > 100Mi
    maximumTotalDecrease: 70          # Never decrease more than 70% total

Current behavior: Memory decreases are applied in full in a single reconciliation; allowUnsafeMemoryDecrease and gradualDecreaseConfig are inert until implemented.

Min/max constraints that limit recommendations:

resourceBounds:
  cpu:
    min: 10m      # Never recommend less than 10m
    max: 4000m    # Never recommend more than 4000m
  memory:
    min: 64Mi     # Never recommend less than 64Mi
    max: 8Gi      # Never recommend more than 8Gi

When multiple policies match the same workload, the policy with the highest weight takes precedence:

spec:
  weight: 200  # Higher weight = higher priority (default: 100)

Now that you understand the terminology, learn about:

• Operational Modes
• Update Strategies
• Safety Model