Policy Configuration Guide

• Automation Strategies
• Cluster Automation Strategies
• Proactive Policies
• Cluster Proactive Policies
• Static Policies
• Multi-Policy Container Rightsizing
• Cluster Compaction Policies
• Rollback Policies

​

Configuration Model

• Strategy defines how resizing is allowed to happen.
• Policy defines where that behavior applies and whether targets come from recommendations or fixed resource values.

• AutomationStrategy and ClusterAutomationStrategy define resize behavior.
• ProactivePolicy and ClusterProactivePolicy apply recommendation-driven automation coming from Kubex.
• StaticPolicy and ClusterStaticPolicy apply fixed request and limit values.
• ClusterCompactionPolicy applies active bin-packing and descheduler/scheduler compaction behavior across namespaces.
• PodAffinityPolicy applies preferred hostname-based node affinity to replacement pods and can force eviction-based rescheduling when its affinity rule must be enforced during evaluation.
• ContainerArgsPolicy applies named command-line argument operations to selected workload containers during pod admission and can optionally converge existing pods through eviction.
• RollbackPolicy and ClusterRollbackPolicy enable and configure rollback monitoring and backoff settings. These policies are required for rollback functionality - without a matching policy, workloads will not be monitored for health failures and rollback will not occur.

• ProactivePolicy references a namespaced AutomationStrategy in the same namespace.
• StaticPolicy references a namespaced AutomationStrategy in the same namespace and also includes explicit resources.
• ClusterProactivePolicy references a ClusterAutomationStrategy.
• ClusterStaticPolicy references a ClusterAutomationStrategy and also includes explicit resources.
• ClusterCompactionPolicy manages compaction implementation mode and scope for active bin-packing, including per-policy descheduler placement and node selectors.

​

Helm-Managed Mapping

• ClusterAutomationStrategy
• ClusterProactivePolicy

• AutomationStrategy
• ProactivePolicy
• StaticPolicy
• ClusterStaticPolicy
• RollbackPolicy
• ClusterRollbackPolicy
• ContainerArgsPolicy

​

Values To Resource Mapping

​

Namespace wildcards in scope[].namespaces.values

scope:
  - name: platform
    namespaces:
      operator: In
      values: ["prod-*", "staging"]

• Wildcard patterns must be enclosed in double quotes (e.g., "prod-*", not prod-*) to ensure proper YAML parsing.
• maxAnalysisAgeDays is written to generated ClusterProactivePolicy resources, not to generated strategies.
• ReplicaSet is not supported in allowedPodOwners; use Deployment to cover Deployment-managed pods.
• StrimziPodSet support is opt-in in allowedPodOwners.
• Model is included in default workload types when policy workloadTypes is omitted. Keep allowedPodOwners: [Model] when you want Helm-generated scope restricted to KubeAI Model objects only.
• Helm can reference a ClusterAutomationStrategy that was created outside Helm if the names match.

scope:
  - name: kubeai-models
    policy: balanced
    namespaces:
      operator: In
      values: ["*"]
    allowedPodOwners:
      - Model

​

Strategy Settings Exposed By Helm

• enablement.cpu.requests.*
• enablement.cpu.limits.*
• enablement.memory.requests.*
• enablement.memory.limits.*
• inPlaceResize.*
• podEviction.*
• safetyChecks.* except maxAnalysisAgeDays, which is written to ClusterProactivePolicy

​

When To Manage CRs Outside Helm

• namespaced strategies or policies
• fixed-resource policies
• cluster proactive policies that are not tied to chart values
• cluster automation strategies that are shared, versioned, or promoted independently of Helm releases
• advanced strategy safety checks beyond the Helm-managed subset
• scheduling windows that restrict when automation can run

​

PodAffinityPolicy Behavior

• Admission always injects preferred kubernetes.io/hostname In [...] node affinity into newly created replacement pods.
• During policy evaluation, eviction is enabled whenever the managed preferred hostname affinity on the pod would need to change.
• spec.affinity.checkCurrentNodeSatisfiesAffinity defaults to false.
• When spec.affinity.checkCurrentNodeSatisfiesAffinity is true, policy evaluation also checks the current node hostname. If the running pod is on a node whose kubernetes.io/hostname label is not in spec.affinity.nodes, eviction is enabled even when the pod already has the intended managed affinity.

• Enabling spec.affinity.checkCurrentNodeSatisfiesAffinity can cause eviction loops if the workload cannot actually land on one of the intended nodes. This can happen when scheduler constraints, taints, missing tolerations, topology rules, resource pressure, or other placement rules keep replacement pods off the target nodes.
• Prefer enabling this setting only when you know the target nodes are schedulable for the workload and the preferred hostname list is stable.

​

ContainerArgsPolicy Behavior

apiVersion: rightsizing.kubex.ai/v1alpha1
kind: ContainerArgsPolicy
metadata:
  name: inference-server-args
spec:
  scope:
    workloadTypes: [Deployment, StatefulSet]
    namespaceSelector:
      operator: In
      values: ["inference-*"]
    labelSelector:
      matchLabels:
        app: model-server
  containers:
    "*":
      args:
        - name: --disable-log-stats
          operation: Remove
    server:
      args:
        - name: --gpu-memory-utilization
          value: "0.8"
        - name: --enable-prefix-caching
        - name: -v
          value: "3"
  replaceExistingPods: false
  weight: 100

• operation defaults to AddOrUpdate; Remove deletes every matching equals or split-form occurrence.
• Omitted value emits a valueless flag. value: "" emits an explicit empty value.
• Existing --option=value, --option value, and -o value forms are replaced in place when possible. Missing valued options append in split form.
• Duplicate existing options are collapsed. Duplicate policy entries remain in declared order.
• Wildcard rules apply to all regular containers and restartable sidecars. A named container rule overrides wildcard entries with the same option name; missing named containers are skipped.
• Option names must be literal names beginning with - or --, with no whitespace or =. Combined short flags, attached short values, shell strings, positional edits, and command edits are unsupported.
• Malformed existing argument streams use best-effort replacement; unrelated arguments keep their order.
• This API does not parse shell strings, edit command or positional arguments, detect executables/vLLM, merge policies, patch workload templates, or evict pods directly.

​

Scope Design Guidance

• Prefer mutually exclusive scopes when multi-policy rightsizing is disabled. When enabled, overlapping same-kind resource policies can contribute to separate container/resource targets. See Multi-Policy Container Rightsizing.
• Use weight when policies can recommend the same target.
• Enable globalConfiguration.multiPolicyContainerRightsizingEnabled when same-kind policies need to contribute independently. By default, one policy of each kind contributes per workload.
• Start with narrow namespace and label selectors before widening scope.
• Exclude system and platform namespaces from broad proactive automation.
• Use static policies when exact requests and limits matter more than recommendation-driven tuning.

​

Precedence And Overlap

​

Policy Type Precedence

• ContainerArgsPolicy: priority 100
• StaticPolicy and ClusterStaticPolicy: priority 90
• ProactivePolicy and ClusterProactivePolicy: priority 70

• Start from the default PolicyEvaluation example in Policy Evaluation.
• Change the priorities so proactive policy types win:
  • Set ProactivePolicy and ClusterProactivePolicy to priority: 90
  • Set StaticPolicy and ClusterStaticPolicy to priority: 70