Apply MDA optimization with YAML

Pod rightsizing behavior is configured through policy resources.

Each policy must include a complete set of configuration parameters. Policies do not inherit values from cluster-level defaults.

Pod rightsizing configuration sample

Values inside [ ] are user-specified placeholders.

New Sample

apiVersion: rightsizing.kompass.zesty.co/v1alpha1
kind: Policy
metadata:
  # [string] Unique name identifier for this policy instance.
  name: balanced
spec:
  # [integer] Policy priority. If a workload matches multiple policies,
  # the policy with the lower numeric value has higher priority.
  priority: 0

  # [string] Human-readable description explaining the operational
  # target and behavior of this policy.
  description: "Balances cost and stability for general workloads by using moderate buffers and stable recommendations."

  # [array] Explicit list of workloads managed by this policy.
  # Leave empty to select workloads using appSelector.
  appList: []

  # [object] Selects workloads managed by this policy based on workload
  # labels and namespaces.
  appSelector:
    labels:
      matchLabels: {}
      matchExpressions: []
    namespaces:
      operator: Include
      values: []

  # [string] Period of historical workload metrics that Kompass uses to
  # generate recommendations.
  lookbackPeriod: "24h"

  # [string] Minimum time between consecutive rightsizing changes to the
  # same workload. Longer periods promote greater stability.
  cooldownPeriod: "2h"

  # [integer] Minimum percentage of the lookback period for which metrics
  # must be available before Kompass generates a Pod rightsizing recommendation.
  dataCoveragePercentage: 80

  # CPU resource tuning and optimization settings.
  cpu:
    # [string] Specifies how CPU usage samples are aggregated over the
    # lookback period when generating recommendations.
    optimizationStrategy: "p95"

    # [string] Specifies how CPU usage is aggregated across Pod replicas
    # for each sample.
    replicaAggregationMethod: "max"

    # [integer] Percentage added to the recommended CPU request as a
    # safety buffer.
    bufferPercentage: 20

    # [integer] Minimum percentage difference between the current and
    # recommended CPU requests required for Kompass to apply a change.
    minimumImpactPercentage: 10

    # [string] Minimum increase in CPU request that Kompass can apply in
    # a scale-up change.
    minimumStepForScaleUp: 100m

    # [string] Minimum CPU request that Kompass can set in a scale-down
    # change.
    minimumValueForScaleDown: 10m

    # [boolean] Specifies whether CPU throttling events are ignored when
    # evaluating rollback of a rightsizing change.
    ignoreThrottlingEvent: false

  # Memory resource tuning and optimization settings.
  memory:
    # [string] Specifies how memory usage samples are aggregated over the
    # lookback period when generating recommendations.
    optimizationStrategy: "p99"

    # [string] Specifies how memory usage is aggregated across Pod replicas
    # for each sample.
    replicaAggregationMethod: "max"

    # [integer] Percentage added to the recommended memory request as a
    # safety buffer.
    bufferPercentage: 30

    # [integer] Minimum percentage difference between the current and
    # recommended memory requests required for Kompass to apply a change.
    minimumImpactPercentage: 10

    # [string] Minimum increase in memory request that Kompass can apply
    # in a scale-up change.
    minimumStepForScaleUp: 256Mi

    # [string] Minimum memory request that Kompass can set in a scale-down
    # change.
    minimumValueForScaleDown: 256Mi

    # [boolean] Specifies whether out-of-memory events are ignored when
    # evaluating rollback of a rightsizing change.
    ignoreOomEvent: false

  # [boolean] Specifies whether in-place resource updates are preferred
  # when supported. In-place updates require Kubernetes 1.33 or later.
  preferInPlace: true

  # [boolean] Specifies whether to evict a Pod when an in-place rightsizing
  # action results in Deferred status.
  evictPodsInDeferredState: true

Pod rightsizing policy parameters reference

All parameters are validated when a policy is created or updated. Policies with missing or invalid parameters cannot be applied.

Define custom replica aggregation method values

You can define custom values for the CPU and memory replica aggregation method. This can be useful if the fixed values are overly aggressive.

To define custom aggregation method figures, you define values for custom1 and custom2 in Helm values.yaml, then define the value in the policy configuration as custom value 1 or custom value 2.

To define custom values:

1. Add the custom definition to Helm values.yaml:

   rightsizing:
     config:
       customReplicaAggregationMethods:
         cpu:
           custom1: 70
           custom2: 71
         memory:
           custom1: 80
           custom2: 81

   Note that both CPU and memory are in the same section.

2. In the policy on the cluster, change the value to the desired value.

   For example, to set the memory value to 80, change the value in the policy spec.memory.replicaAggregationMethod to custom value 1.

The following table shows the fixed parameter values in the Pod rightsizing built-in policies:

You cannot delete or change built-in policies parameters.

To create a custom policy, see the “Create a custom policy” section in this article.

Boost startup resources

Some workloads require higher CPU or memory during initialization than during normal operation. To accommodate this, you would need to manually assign extra resources for startup (to prevent OOM or throttling) and then to reduce those assignments for ongoing operation.  

With Pod rightsizing and Startup boost, you can temporarily increase CPU and memory resources for new Pods during initialization. After a configured duration, the resources automatically revert to initial values and then Pod rightsizing is applied.

With Startup boost:

• Startup-related spikes are excluded from the steady state recommendation logic.

• Steady-state requests are aligned with actual runtime usage.

You apply Startup boost to a workload by adding startupBoost to a custom Pod rightsizing policy that manages the workload.

spec:
   startupBoost:
 	duration: 5m
 	cpu:
   	  multiplier: 1.5
 	memory:
   	  multiplier: 3

Startup boost limitations and considerations

• Applies to all containers in a Pod.

• Requires in-place Pod mutation support.

• Cannot be used if preferInPlace: false

• If a Pod needs to be evicted to a different node due to insufficient node capacity, it will be evicted even if the policy includes: spec.evictPodsInDeferredState = false

For more information about creating custom policies, see the “Create a custom policy” section in this article.

Selective Pod rightsizing

There may be cases where you want to manually manage workload memory resources while allowing Pod rightsizing to manage CPU resources, or vice versa.

For example, you may want separate control for memory-critical or CPU-critical applications (such as Java applications), or for testing purposes.

With Selective Pod rightsizing, you can apply Pod rightsizing to only one resource while manually managing the other resource.

To use Selective Pod rightsizing, create a custom policy and remove the entire configuration block for the resource that you want to manage manually.

For example, to apply Pod rightsizing only to CPU resources, remove the entire memory section from the policy:

memory:
  bufferPercentage: 40
  ignoreOomEvent: false
  minimumImpactPercentage: 10
  minimumStepForScaleUp: 256Mi
  minimumValueForScaleDown: 256Mi
  optimizationStrategy: max
  replicaAggregationMethod: max 

Replica optimization behavior is configured through policy resources.

Each policy must include a complete set of configuration parameters. Policies do not inherit values from cluster-level defaults.

Replica optimization can be applied only to workloads that are already managed by a Pod rightsizing policy.

If a Replica optimization policy matches a workload that is not managed by a Pod rightsizing policy, the Replica optimization policy is not applied to that workload. The policy remains valid and no validation error is generated.

When a workload is managed by both a Pod rightsizing policy and a Replica optimization policy, the workload operates in MDA mode.

Replica optimization configuration sample

Values inside [ ] are user-specified placeholders.

This sample is for the Balanced, built-in policy.

apiVersion: horizontalscaling.kompass.zesty.co/v1alpha1
kind: Policy
metadata:
  name: balanced
spec:
  # Replica optimization does not reduce minimum replicas below this value.
  absoluteMinimumReplicas: 2
  appSelector:
    labels: {}
    namespaces:
      operator: Include
      values: []
  description: Balanced setup with stable recommendations for production environments.
  # Lower values have higher priority.
  priority: 0

Replica optimization policy parameters reference

All parameters are validated when the policy is created or updated.

The following table shows the fixed parameter values in the Replica optimization built-in policies:

You cannot delete or change built-in policies parameters.

To create a custom policy, see the “Create a custom policy” section in this article.

In-policy selection (configured in the policy):

• appList — explicitly match specific workloads by kind, name, and namespace

• appSelector.labels — match workloads dynamically based on Kubernetes labels

• appSelector.namespaces — filter the label-matched workloads by namespace

Workload-side matching (configured on the workload)

• Policy annotation — explicitly match a workload to a policy by referencing the policy name in an annotation

When multiple selection mechanisms apply to the same workload, optimization policies use priority and conflict resolution rules to determine which policy manages it.

If neither appList nor appSelector.labels is defined, the policy does not match any workloads through selectors; workloads can still be matched by annotation.

Use appList or appSelector.labels to target workloads, and use appSelector.namespaces to narrow that selection.

Common policy selection use cases

The following table shows common policy selection use cases:

Explicit workload inclusion (appList)

Explicit workload inclusion (appList) matches specific workloads by kind, name, and namespace.

In this topic, appList refers to the explicit workload inclusion mechanism, which is configured using the appList field in the policy.

Use appList to target specific workloads by kind, name, or namespace.

appList:
  - kind: <workload-kind>
    name: <workload-name>
    namespace: <namespace>

Behavior:

• Matches the workloads specified in the appList entry.

• Takes precedence over label-based matching.

• If only namespace is specified, the policy matches all supported workloads in that namespace.

• name and kind can’t be used by themselves; specify them together with namespace.

Label-based selection

Label-based selection (appSelector.labels) dynamically matches workloads based on Kubernetes labels.

appSelector:
  labels:
    matchLabels:
      <label-key>: <label-value>
    matchExpressions:
      - key: <label-key>
        operator: <operator>
        values:
          - <value>

Supported operators: In, NotIn, Exists, DoesNotExist

Behavior:

• matchLabels and matchExpressions are evaluated using AND logic.

• Multiple matchExpressions are also evaluated using AND logic.

• Only workloads that match all conditions are matched to the policy.

Namespace filtering

Namespace filtering (appSelector.namespaces) scopes label-based selection to specific namespaces by including or excluding namespaces.

appSelector:
  namespaces:
    operator: <Include | Exclude>
    values:
      - <namespace>

Behavior:

• Applies only to workloads matched by label selectors.

• The kube-system namespace is always excluded.

Annotation-based matching

A workload can be explicitly matched to a policy using a Kubernetes annotation.

Pod rightsizing

metadata:
  annotations:
    rightsizing.kompass.zesty.co/policy: <any rightsizing policy>

Replica optimization

metadata:
  annotations:
    horizontalscaling.kompass.zesty.co/policy: <any horizontal scaling policy>

Behavior:

• The referenced policy matches the workload, and the corresponding optimization applies to that workload.

• Annotation-based matching overrides selector-based selection and priority.

• Removing the annotation removes this explicit match.

User interface and YAML:

• The UI assigns a policy to a workload by creating or updating the workload’s policy annotation.

• You can manage or modify Pod rightsizing in the UI only for workloads matched to a policy by annotation.

• For workloads matched by appList or label selectors, make changes using YAML.

Examples

The following table shows example uses of workload selection:

Priority rules

• A policy must define a priority value.

• Lower numeric values indicate higher priority. For example, priority 1 takes precedence over priority 2.

• Priority values must be unique per cluster. If you create or update a policy with a priority value that is already used, the request is rejected with a validation error.

Policy resolution order

Pod rightsizing determines the managing policy using the following resolution order:

1. Annotation-based resolution: Annotation-based assignment overrides selector-based matching and priority independently for Pod rightsizing and Replica optimization policies.

2. Selector-based resolution: If a workload matches multiple policies through appList or label selectors, the policy with the highest priority manages the workload.

A workload is managed by at most one Pod rightsizing policy and one Replica optimization policy at a time.

To confirm which policy manages a workload:

1. Check whether the workload has a policy annotation.
   If metadata.annotations.<policy-annotation-key> is set, the referenced policy manages the workload (and overrides selector-based selection and priority).

2. If no policy annotation exists, determine which policies match the workload via appList and appSelector rules.

3. If multiple policies match, the policy with the lowest priority value manages the workload.

4. If the workload is not matched by any policy, it is unmanaged and no optimization is applied.